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 ("system tokens") represent you, your business or organization, or people within your business or organization. The main advantage of these tokens is that they are long-lived and can represent automated services within your business that don't require any user input.
System tokens rely on system users. 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 admins or employees.
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 portfolio.
Admin system users are useful if your app needs access to all of the business portfolio's assets, without having to manually grant business asset access to each asset whenever it is created, or shared with your business portfolio.
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.
Employee System Users
Employee system users must be granted access to individual WhatsApp Business Accounts that are owned by, or shared with, your business portfolio. 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.
Generating System User Access Tokens
To generate a system token, access the Business settings panel and then click System Users:
Click the +Add button, and in the Create system user window that appears, enter a system user name and assign it an Admin or Emplyee role:
Once the admin system user has been created, it will appear in the list of system users. Click the system user's name to display the asset assignment overlay:
Click the Assign assets button to display the Select assets and assign permissions window:
Select your app and grant your system user the Manage app permission, then click the Assign assets button to confirm and dismiss the window.
Back in the System Users panel, reload the page to confirm that your system user has been granted Full control of your app. It may take a few minutes for the permissions to be granted, so reload the page after a few minutes if your app doesn't appear as an assigned asset. Once the asset has been assigned, it should look like this:
Once you see that your system user has been granted full control of your app, in the asset assignment overlay, click the Generate token button. In the window that appears, select your app, choose a token expiration preference, and assign your app these three Graph API permissions:
- business_management
- whatsapp_business_management
- whatsapp_business_management
You can search for "business" to find these permissions quickly:
Click the Generate token button and copy the token when it appears.
Business Integration System User Access Tokens
Business Integration System User access tokens ("business 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
| Type of Call | Endpoint |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
| Type of Call | Endpoint |
|---|---|
|
|
|
|
|
|
|
|
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.
