Step 1: Get System User Access Token
Graph API calls use access tokens for authentication. For more information, see Access Tokens. We recommend using your system user to generate your token.
To generate a system user access token:
- Go to Business Manager > Business Settings > Users > System Users to view the system user you created.
- Click on that user and select Add Assets. This action launches a new window.
- Under Select Asset Type on the left side pane, select Apps. Under Select Assets, choose the Meta app you want to use (your app must have the correct permissions). Enable Develop App for that app.
- Select Save Changes to save your settings and return to the system user main screen.
- Now you are ready to generate your token. In the system user main screen, click Generate Token and select your Meta app. After selecting the app, you see a list of available permissions. Select
whatsapp_business_management,whatsapp_business_messaging, andbusiness_management. Click Generate Token. - A new window opens with your system user, assigned app and access token. Save your token.
- Optionally, you can click on your token and see the Token Debugger. In your debugger, you should see the two permissions you have selected. You can also directly paste your token into the Access Token Debugger.
Step 2: Set up Webhooks
With Webhooks set up, you can receive real-time HTTP notifications from the WhatsApp Business Platform. This means you get notified when, for example, you get a message from a customer or there are changes to your WhatsApp Business Account (WABA).
To set up your Webhook, you need to create an internet-facing web server with a URL that meets Meta’s and WhatsApp’s requirements. See Creating an Endpoint for instructions on how to do that. If you need an endpoint for testing purposes, you can generate a test Webhooks endpoint.
App Setup
Once the endpoint is ready, configure it to be used by your Meta app:
In your App Dashboard, find the WhatsApp product and click Configuration. Then, find the webhooks section and click Configure a webhook. After the click, a dialog appears on your screen and asks you for two items:
- Callback URL: This is the URL Meta will be sending the events to. See the Webhooks, Getting Started guide for information on creating the URL.
- Verify Token: This string is set up by you, when you create your webhook endpoint.
After adding the information, click Verify and Save.
Back in the App Dashboard, click WhatsApp > Configuration in the left-side panel. Under Webhooks, click Manage. A dialog box will open with all the objects you can get notified about. To receive messages from your users, click Subscribe for messages.
You only need to set up Webhooks once for every application you have. You can use the same Webhook to receive multiple event types from multiple WhatsApp Business Accounts. For more information, see our Webhooks section.
At any time, each Meta App can have only one endpoint configured. If you need to send your webhook updates to multiple endpoints, you need multiple Meta Apps.
Step 3: Subscribe to your WABA
To make sure you get notifications for the correct account, subscribe your app:
curl -X POST \
'https://graph.facebook.com/{{Version}}/WHATSAPP_BUSINESS_ACCOUNT_ID/subscribed_apps' \
-H 'Authorization: Bearer ACCESS_TOKEN'
If you get the response below, all Webhook events for the phone numbers under this account will be sent to your configured Webhooks endpoint.
{
"success": "true"
}
Step 4: Get Phone Number ID
To send messages, you need to register the phone number you want to use —this is the business phone number we mentioned in Before You Start.
Before you can proceed to registration, you need to find that phone number’s ID. To get your phone number’s ID, make the following API call:
curl -X GET \
'https://graph.facebook.com/{{Version}}/WHATSAPP_BUSINESS_ACCOUNT_ID/phone_numbers' \
-H 'Authorization: Bearer ACCESS_TOKEN'
If the request is successful, the response includes all phone numbers connected to your WABA:
{
"data": [
{
"verified_name": "Jasper's Market",
"display_phone_number": "+1 631-555-5555",
"id": "1906385232743451",
"quality_rating": "GREEN"
},
{
"verified_name": "Jasper's Ice Cream",
"display_phone_number": "+1 631-555-5556",
"id": "1913623884432103",
"quality_rating": "NA"
}
]
}
Save the ID for the phone number you want to register. See Read Phone Numbers for more information about this endpoint.
Migration Exception
If you are migrating a phone number from the On-Premises API to the Cloud API, there are extra steps you need to perform before registering a phone number with the Cloud API. See Migrate Between On-Premises and Cloud API for the full process.
Step 5: Register Phone Number
With the phone number’s ID in hand, you can register it. In the registration API call, you perform two actions at the same time:
- Register the phone.
- Enable two-step verification by setting a 6-digit registration code —you must set this code on your end. Save and memorize this code as it can be requested later. Setting up two-factor authentication is a requirement to use the Cloud API.
Sample request:
curl -X POST \
'https://graph.facebook.com/{{Version}}/FROM_PHONE_NUMBER_ID/register' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-d '{
"messaging_product": "whatsapp",
"pin": "6_DIGIT_PIN"
}'
Sample response:
{
"success": "true"
}
Embedded Signup Users
A phone number must be registered up to 14 days after going through the Embedded Signup flow. If a number is not registered during that window, the phone must go through to the Embedded Signup flow again prior to registration.
Step 6: Receive a Message From Consumer App
Once participating customers send a message to your business, you get 24 hours of free messages with them —that window of time is called the customer service window. For testing purposes, we want to enable this window, so you can send as many messages as you would like.
From a personal WhatsApp iOS/Android app, send a message to the phone number you just registered. Once the message is sent, you should receive an incoming message to your Webhook with a notification in the following format.
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "16315551234",
"phone_number_id": "PHONE_NUMBER_ID"
},
"contacts": [
{
"profile": {
"name": "Kerry Fisher"
},
"wa_id": "16315555555"
}
],
"messages": [
{
"from": "16315555555",
"id": "wamid.ABGGFlA5FpafAgo6tHcNmNjXmuSf",
"timestamp": "1602139392",
"text": {
"body": "Hello!"
},
"type": "text"
}
]
},
"field": "messages"
}
]
}
]
}
Step 7: Send a Test Message
Once you have enabled the customer service window, you can send a test message to the consumer number you used in the previous step. To do that, make the following API call:
curl -X POST \
'https://graph.facebook.com/{{Version}}/FROM_PHONE_NUMBER_ID/messages' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-d '{
"messaging_product": "whatsapp",
"to": "16315555555",
"text": {"body" : "hello world!"}
}'
If your call is successful, your response will include a message ID. Use that ID to track the progress of your messages via Webhooks.
Sample response:
{
"id":"wamid.gBGGFlaCGg0xcvAdgmZ9plHrf2Mh-o"
}
With the Cloud API, there is no longer a way to explicitly check if a phone number has a WhatsApp ID. To send someone a message using the Cloud API, just send it directly to the customer's phone number —after they have opted-in. See Reference, Messages for examples.