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

System Users

System users can be used to generate System User Access Tokens, which are typically what you will be using in API requests. 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.

If your app will be accessing WhatsApp Business Accounts and assets shared with your business, we recommend creating an admin system user. If your app will only be accessing data owned by your business, either type is sufficient.

To create a system user:

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

Admin System Users

By default, admin system users have full access to all WhatsApp Business Accounts and assets owned by, or shared with, the Meta 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 access to each WhatsApp Business Account that has been shared with you.

Note that you can override an admin system user's default access by granting partial access on a per-WhatsApp Business Account basis.

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 full or partial access to each WhatsApp Business Account that the system user needs to access.

System User Access Tokens

We recommend that you use system user access tokens to access the Business Management API and Cloud API. To generate a System User access token after creating a system user:

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

Include your token in an authorization request header, preceded by Bearer. For example:

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

User Access Tokens

Although user access tokens are supported, we recommend that you use system user access tokens to access the Business Management API and Cloud API unless you are implementing Facebook Login.

WhatsApp Business Account Access

Many endpoints require the user whose token is included in API requests to also be granted partial or full access to the WhatsApp Business Account being queried (or its assets). If the user does not have access, the API will return error code 200.

Granular access can be set for any user, including system users. Granular access for system users can be useful if you want to restrict access to certain assets for groups of people. 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.

To designated user access on a WhatsApp Business Account or its assets:

  1. Sign into the Meta Business Suite.
  2. Locate your business account in the top-left dropdown menu and click its Settings (gear) icon.
  3. Click Business settings.
  4. Navigate to Accounts > WhatsApp Accounts.
  5. Select the appropriate WhatsApp Business Account.
  6. Select the WhatsApp Account Access tab.
  7. Click the +Add people button.
  8. 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/v18.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/v18.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

Next Steps