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 business account.
• A business app, associated with your business account.
• Either a System User access token or a User access token.
• The whatsapp_business_management permission
• If your app needs to access endpoints that target your business account, you will also need the business_management permission

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

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