WhatsApp Business Platform > Business Management API

Overview

The Business Management API allows you to create and manage WhatsApp-related business assets, such as WhatsApp Business Accounts and message templates. The API is built on the Marketing API and leverages some of its endpoints, so this documentation may contain links to the Marketing API documentation where appropriate.

Requirements

A Meta Business Account.
A WhatsApp Business Account, associated with your Meta Business Account.
A business app, associated with your Meta Business Account.
A Business Integration System User access token, a System User access token, or a User access token.
The whatsapp_business_management permission.
If your app accesses endpoints that target your Meta Business Account, you will need the business_management permission.
If your app accesses Cloud API endpoints, you will need the whatsapp_business_messaging permission.

Access Tokens

The platform supports the following access token types. The type you use depends on who will be using your application, and whether or not you are a Solution Provider.

If you are a direct developer, meaning only you or your business will be accessing your own data, use a System User access token.
If you are a Tech Provider, use a Business Integration System User access token.
If you are a Solution Partner, use System User access tokens to share your line of credit with newly onboarded customers, and Business Integration System User access tokens for everything else.

System User Access Tokens

System User access tokens represent you, your business or organization, or people within your business or organization. The main advantage of these tokens is that they do not expire, and they can represent automated services within your business that don't require any user input.

System User access tokens are the only type of token that can be used by Solution Partners to share credit lines with onboarded customers.

Before you can generate a System User access token, you must create a system user. Most endpoints check if the user identified by the token has access to the queried resource. If the user does not have access to the resource, the request will be rejected with error code 200.

System users can be employees or admins.

Employee System Users

Employee system users must be granted access to individual WhatsApp Business Accounts that are owned by, or shared with, the Meta business. If your app will only need access to a few WhatsApp Business Accounts that you own, an employee system user should be sufficient.

Once created, you must grant Partial or Full business asset access to each WhatsApp Business Account that the system user needs to access.

Admin System Users

By default, admin system users have full access to all WhatsApp Business Accounts and their assets owned by or shared with you or your business.

Admin system users are useful if your app needs to access WhatsApp Business Accounts that are newly shared with your business; if you are using an employee system user, you must manually grant business asset access to each WhatsApp Business Account that has been shared with you.

Note that you can override an admin system user's default business asset access by granting partial access on a per-WhatsApp Business Account basis. See Business Asset Access to learn how to set and override access.

Creating System Users

To create a system user:

Sign into the Meta Business Suite.
Locate your business account in the top-left dropdown menu and click its Settings (gear) icon.
Click Business settings.
Navigate to Users > System users.
Click the Add button and create either an admin or employee system user.

Generating System User Access Tokens

To generate a System User access token after creating a system user:

Sign into the Meta Business Suite.
Locate your business account in the top-left dropdown menu and click its Settings (gear) icon.
Click Business settings.
Navigate to User > System users.
Select the appropriate system user from the list of system users.
Click the Generate new token button.
Select the app that will use the token.
Select any Graph API permissions the app needs to function properly and generate the token.

Business Integration System User Access Tokens

Business Integration System User access tokens are scoped to individual onboarded customers and should be used by Tech Providers and Solution Partners when accessing onboarded customer data.

These tokens are useful for apps that perform programmatic, automated actions on customer WhatsApp Business Accounts, without having to rely on input from an app user, or requiring future re-authentication.

To generate a Business Integration System User access tokens, you must implement Embedded Signup (configured with Facebook Login for Businesses) and exchange the code returned to you when a customer completes the flow.

See the Embedded Signup document and the Business Integration System User access tokens document to learn more about these tokens and how they are generated.

User Access Tokens

Although User access tokens are supported and can be used by all app developers, you likely will only use them when you first use the App Dashboard to send your first test message. As you develop your app, however, you most likely will switch to a System User access token (and eventually a Business System User access token, if you are Tech Provider or Solution Provider). This is because user access tokens expire quickly, so you will have to keep generating a new one every few hours.

There are several ways to generate a User access token:

Access the App Dashboard > WhatsApp > API setup panel. This panel always generates a new User access token whenever you visit it. The token is automatically scoped to your user, since you are signed into your developer account when you access the panel.
Use Graph API Explorer.
Implement Facebook Login.

Using Tokens In Requests

When making API requests, include your token in an authorization request header, preceded by Bearer. For example:

curl 'https://graph.facebook.com/v18.0/102290129340398/message_templates' \
-H 'Authorization: Bearer EAAJB...' \

Business Asset Access

After creating a system user, you must set business asset access levels. Many endpoints require the system user whose token is included in API requests to have either Partial or Full business asset access to the WhatsApp Business Account being queried (or its assets). If the system user does not have this access, these endpoints will return error code 200.

Note that if you set a system user's business asset access on a WhatsApp Business Account to Partial access, you can further restrict access to certain assets or actions on the WhatsApp Business Account. For example, if you have a large business and want a certain department to only have read access to a WhatsApp Business Account's template and business phone number data, you could create a system user for that department and set granular access to view only for that data.

To set business asset access on a WhatsApp Business Account:

Sign into the Meta Business Suite.
Locate your business account in the top-left dropdown menu and click its Settings (gear) icon.
Navigate to Accounts > WhatsApp Accounts.
Select the appropriate WhatsApp Business Account.
Select the WhatsApp Account Access tab.
Click the +Add people button.
Select the appropriate system user and assign appropriate access levels on the WhatsApp Business Account.

Testing Endpoints

We recommend using our Postman collection or cURL when testing endpoints. Although you can use the Graph API Explorer tool, it passes tokens as query string parameters, which we advise against (pass tokens in request headers instead).

Get Information About a Business

To get information about a business, send a GET request to the WhatsAppBusinessAccount endpoint where <WHATSAPP_BUSINESS_ACCOUNT_ID> is your WhatsApp Business Account ID.

Example Request

curl -i -X GET 'https://graph.facebook.com/v21.0/<WHATSAPP_BUSINESS_ACCOUNT_ID>' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Example Response

{
  "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
  "name": "Your WhatsApp Business Account Name",
  "timezone_id": "1",
  "message_template_namespace": "05155c78_261e_4b2f_82b3_d7958d4cf75f"
}

To get specific information about a business, such as name, message templates and phone numbers, send a GET request to the WhatsAppBusinessAccount endpoint where <WHATSAPP_BUSINESS_ACCOUNT_ID> is your WhatsApp Business Account ID and set the fields parameter to a list of items you would like returned.

Example Request

curl -i -X GET 'https://graph.facebook.com/v21.0/<WHATSAPP_BUSINESS_ACCOUNT_ID>?fields=id,name,message_templates,phone_numbers' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Example Response

{
  "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
  "name": "Your WhatsApp Business Account Name",
  "message_templates": {
    "data": [
      {
        "name": "hello_world",
        "components": [
          {
            "type": "HEADER",
            "format": "TEXT",
            "text": "Hello World"
          },
          {
            "type": "BODY",
            "text": "Welcome and congratulations!! This message demonstrates your ability to send a message notification from WhatsApp Business Platform. Thank you for taking the time to test with us."
          },
          {
            "type": "FOOTER",
            "text": "WhatsApp Business Team"
          }
        ],
        "language": "en_US",
        "status": "APPROVED",
        "category": "ACCOUNT_UPDATE",
        "id": "307191531401674"
      },
      {
        "name": "sample_flight_confirmation",
        "components": [
          {
            "type": "HEADER",
            "format": "DOCUMENT"
          },
          {
            "type": "BODY",
            "text": "Confirmamos tu vuelo a {{1}}-{{2}} para el {{3}}."
          },
          {
            "type": "FOOTER",
            "text": "Este mensaje proviene de un negocio no verificado."
          }
        ],
        "language": "es",
        "status": "APPROVED",
        "category": "TICKET_UPDATE",
      },
      ...

Rate Limits

Requests made by your app to the WhatsApp Business Management API are counted against your app’s count. An app’s call count is the number of calls it can make during a rolling one hour. For the following WhatsApp Business Management API, your app can make 200 calls per hour, per app, per WhatsApp Business Account (WABA) by default. For active WABAs with at least one registered phone number, your app can make 5000 calls per hour, per app, per active WABA.

Type of Call	Endpoint
`GET`	`/{whatsapp-business-account-id}`
`GET`, `POST`, and `DELETE`	`/{whatsapp-business-account-id}/assigned_users`
`GET`	`/{whatsapp-business-account-id}/phone_numbers`
`GET`, `POST`, and `DELETE`	`/{whatsapp-business-account-id}/message_templates`
`GET`, `POST`, and `DELETE`	`/{whatsapp-business-account-id}/subscribed_apps`
`GET`	`/{whatsapp-business-account-to-number-current-status-id}`

For the following Credit Line APIs, your app can make 5000 calls per hour, per app.

Type of Call	Endpoint
`GET`	`/{business-id}/extendedcredits`
`POST`	`/{extended-credit-id}/whatsapp_credit_sharing_and_attach`
`GET` and `DELETE`	`/{allocation-config-id}`
`GET`	`/{extended-credit-id}/owning_credit_allocation_configs`

To avoid hitting rate limits, we recommend using webhooks to keep track of status updates for message templates, phone numbers, and WABAs.

For more information on how to get your current rate usage, see Headers.

Learn More

Facebook SDKs — To ask users for permissions using Facebook Login, you can implement one of our SDKs.
Marketing API Business Manager – Learn more about the Marketing API Business Manager.
App Review – Learn more about the process to access your own data or data owned by others.
Watch a Set up the WhatsApp Business Platform video.

Next Steps

Guides – Learn what more you can do with the WhatsApp Business Management API.
Explore our Postman Collection

WhatsApp Business Platform | Cloud API | On-Premises API | Business Management API