WhatsApp Cloud 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.
• 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.