Get Started

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.

Before You Start

To interact with Facebook Graph API, you need to register a Facebook app.

Register your App

We recommend this setup to be done by someone with an admin role in the Business Manager containing your WhatsApp Business Accounts. This avoids permission errors.

  1. Register a Facebook app on the Facebook Developers website using your personal profile (don’t worry, the app will belong to the Business Manager in the end). Your app type needs to be Business or None to use the WhatsApp Business Management API. Find more information on App Types in the App Development documentation.
  2. Find your app ID. Go to developers.facebook.com/apps, locate the app you have registered, and click on the app. A new screen opens up. Copy the App ID displayed on top of the page:
  3. Now go to https://developers.facebook.com/apps/{app-id}/settings/advanced to import the app into your Business Manager —replace {app-id} with the ID you got in Step 2. The Business Manager you use should contain your WhatsApp Business Accounts.
  4. Check for additional instructions in the app configuration, especially those related to GDPR that might apply to your specific case.

For more information about registering as a developer, creating your app, app roles, app modes, please see the App Development documentation.

App Review

When you initially register your app it will be set to Development mode. Apps in Development mode are automatically approved for all login permissions, features, and product-specific features for testing purposes. However, these permissions are limited —the app can only use those permissions to access data of users with roles in your app, like admins and developers.

In order to switch your Facebook app from Development mode to Live mode, it must go through App Review. If you want higher rate limits or would like to access a WhatsApp Business Account not in your Business Manager, you need to go through App Review.

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. Make 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 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 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/v12.0/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/v12.0/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/v12.0/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/v12.0/your-whatsapp-business-account-id/message_templates?access_token=your-access-token"

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

Requests made by your app to the WhatsApp Business Management API are counted against your app’s count. An app’s call count is the number of calls it can make during a rolling one hour. For WhatsApp Business Management API, your app can make 5000 calls per hour, per app, per active WhatsApp Business Account (WABA). An active WABA is an account with at least one registered phone number.

The following API calls count towards your limit:
Type of Call Endpoint

GET

/{whats-app-business-account-id}

GET, POST, and DELETE

/{whats-app-business-account-id}/assigned_users

GET

/{whats-app-business-account-id}/phone_numbers

POST and DELETE

/{whats-app-business-account-id}/message_templates

GET, POST, and DELETE

/{whats-app-business-account-id}/subscribed_apps

GET

/{whats-app-business-account-to-number-current-status-id}

To avoid hitting rate limits, we recommend using webhooks to keep track of status updates for message templates, phone numbers and WABAs.

For more information on how to get your current rate usage, see Headers.

Message Template Limits

  • 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 single 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 can be used to create and delete only. We recommend using a separate WhatsApp Business Account to experiment with the WhatsApp Business Management API to avoid mistakes.

Get 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.