WhatsApp Business API

Using the WhatsApp Business Management API

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.

Prerequisites

Implementing the API

To make API calls to this API's endpoints, you will need to do the following:

  1. Acquire an access token through a System User or Facebook Login.
  2. Be able to make API calls using the tool of your choice.

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.

1. Acquire an Access Token Using a System User or Facebook Login

1.1 Deciding how to set up your system

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:

  1. Create a System User in your Business Manager and acquire a non-expiring token to be used for backend system integrations. This works for cases such as “a system from company X generates a weekly report on message volume from a certain WhatsApp Business Account without human intervention”.
  2. Use Facebook Login to acquire a user access token and request specific permissions. This is recommended when actions will be performed on behalf of a user, for example, “user X creates a new message template using a tool built by company Y”.

1.2 Creating a System User

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.

  1. Create a System User (not an “Admin System User”) in the System Users Tab of the Business Manager.
  2. Under the WhatsApp Accounts tab, click on Add People, and select your System User to grant access to the WhatsApp Business Account.
    Add System User to a WhatsApp Business Account
  3. Go to the System Users tab and click Generate Access Token. Select your app and mark the permissions that you need for the application, making sure to request the whatsapp_business_management permission.
    Generate an access token

1.3 Using Facebook Login

  1. Refer to the Facebook Login documentation for information on setting up Facebook Login.
  2. When requesting an access token, make sure to request the 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.

1.4 Additional tips on access token management

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.

2. Making API calls

  1. To make your first calls, we recommend using the Graph API Explorer instead of the writing code straight away.
    Using the Graph API Explorer to make calls to the WhatsApp Business Management API
  2. Make sure your access token has the correct permissions using the Access Token Debugger. Many errors come from insufficient permissions or expired tokens.
    Using the Access Token Debugger to investigate permissions

Permissions Required

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.

API Guides

These documents provide some initial guidance on how to use this API:

API Reference

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:

API call examples

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"

Webhooks

You can set up Webhooks to send you notifications of changes to your WhatsApp business account.

Two types of notifications you can subscribe to are

  • phone_number_name_update — Notifies you when the name review associated with a phone number has a status update.
  • phone_number_quality_update — Notifies you when the quality-related status of a phone number has an update.

See the Webhooks for WhatsApp Business Accounts documentation for more information.

SDKs

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:

  • If you are making calls on behalf of users, you will need Facebook Login. Use the Graph API SDKs to acquire an access token. Calls can be done from the frontend or the access token can be passed to your backend to do calls from there.
  • In the backend, the Facebook Business SDK is probably your best option and is provided in multiple languages such as Java, JavaScript, Python, PHP and Ruby.

API Limits

  • All APIs have a throttle system. Refer to the Rate Limiting documentation for more information.
  • There are also limits on how many message templates a WhatsApp Business Account can have. Creating message templates is throttled at 100 message templates per hour.
  • Each WhatsApp Business Account can have up to 250 message templates. That means 250 message template names, each of them can have multiple language translations. For example, a message template called hello_world translated into two languages counts as a singe message template in regards to this limit.
  • The message template name field is limited to 512 characters.
  • The message template content field is limited to 1024 characters.
  • Remember you cannot currently edit message templates. For now, the API is create and delete only. We recommend using a separate WhatsApp Business Account to experiment with the WhatsApp Business Management API to avoid mistakes.

Getting Support

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.