The WhatsApp Business Management API is based on Facebook's Graph API. API calls are versioned, and the availability of each version is detailed in the Graph API Changelog. Some functionality might also be available under Facebook's Marketing API, which follows some slightly different rules around versioning but uses the same technical infrastructure and authentication framework. This guide is a brief introduction to making API calls and some architectural decisions you will need to make when building your integration.
To make API calls to this API's endpoints, you will need to do the following:
We recommend reading Using the Graph API to understand the API's base concepts. After doing so, you will be more effective when consulting the WhatsApp Business Management API Reference to perform actions.
Both Graph API and Marketing API calls require an access token to be passed as a parameter in each API call. This token can be acquired multiple ways, the following being the most common:
This is recommended for a first setup.
A System User is a Facebook account that can only interact with the system by using API calls. It can have the same permissions as a user within a Business Manager. Refer to the Marketing API's System Users documentation for more information.
whatsapp_business_management permission.
whatsapp_business_management permission. Important! A Facebook app needs to go through review to request most permissions. People with a role on the app (admin, developer, etc.) can request permissions without review, but for third-parties this will fail.
Regardless of your chosen setup, access tokens can expire even if they don't have an expiration date. For example, a token is invalidated if a user changes their password. Your systems should take this into consideration, especially for third-parties. Some Facebook SDKs (e.g., the JavaScript SDK) manage those cases transparently. Refer to the Marketing API's Access Tokens Permissions documentation for more information.
Regardless of authentication method chosen, you will need to request some permissions to call the WhatsApp Business Management API. The whatsapp_business_management permission is required to do everything related to a WhatsApp Business Account. If your tool does any set up related to Business Manager, you might also require the business_management permission.
These documents provide some initial guidance on how to use this API:
In addition to the practical guides, each endpoint has an auto-generated reference listing every field and edge available. Those pages are available for both the Graph API and Marketing API. We recommend starting with guides above, but here's a non-exhaustive list of main endpoints to get you started:
You can retrieve information about each of these API nodes by doing an GET call. This API call returns information about the owner of this access token:
curl -i -X GET \ "https://graph.facebook.com/v3.3/me?access_token=your-access-token"
It's equivalent to calling its id directly, such as with this example where the id is 12345678944534:
curl -i -X GET \ "https://graph.facebook.com/v3.3/12345678944534?access_token=your-access-token"
API nodes have edges that expose the relationships between objects. The API nodes linked above also list all the edges for each node. This API call will return a list of businesses that the owner of the access token has access to:
curl -i -X GET \ "https://graph.facebook.com/v3.3/me/businesses?access_token=your-access-token"
For a list of message templates, the call would be:
curl -i -X GET \ "https://graph.facebook.com/v3.3/your-whatsapp-business-account-id/message_templates?access_token=your-access-token"
Facebook provides multiple SDKs for the Graph API and Marketing API. All of them should be compatible with the same authentication framework using access tokens. Recommendations vary depending on the use case:
hello_world translated into two languages counts as a singe message template in regards to this limit.name field is limited to 512 characters. content field is limited to 1024 characters.Under the hood, all Facebook APIs share the same infrastructure. Searching the Facebook Developers website may reveal more relevant information for your specific situation.
If you are unable to find the information you need, please use WhatsApp's regular Direct Support channel within Business Manager. As a general tip, when an API call fails, a fbtrace_id parameter will be returned. Share this parameter with support for more effective investigation.