Get Started

At this time, this API is only available in alpha and beta to selected partners.

This step-by-step tutorial provides information on how to send your first message. See Before You Start to get a list of the assets you need to have before completing this tutorial.

This guide is divided into three stages:

  • Stage 1: Prepare - First, get the access token you need to use in all of the following API calls. Then, you set up your Webhooks and subscribe to your WABA. Finally, get a phone number's ID and register it.
  • Stage 2: Enable the customer service window - When certain customers send a message to a business, that business gets 24 hours of free messages with them. For testing purposes, we want to enable this window, so you can send as many messages as you would like. To do that, send a test message from the consumer app to the phone number you just registered. Once the message is received, you get a Webhook notification with that number’s WhatsApp ID.
  • Stage 3: Send a message - With a registered phone number, a system user access token, and the WhatsApp ID or the phone number for the person you want to reach, you can send your first message.

If you are a Business Service Provider (BSP), you need to have Embedded Sign Up integrated to use the Cloud API. For more information, see Embedded Signup Overview.

Before You Start

Businesses setting up their integration need to have the following assets:

AssetSpecific Instructions

Business Manager

You can use an existing, or set up a new one. Save the Business Manager ID.

WhatsApp Business Account (WABA)

See Create a WhatsApp Business Account for the WhatsApp Business API for help.

Facebook App

Your app needs to request the following permissions:

  • whatsapp_business_management — Used to manage phone numbers, message templates, registration, business profile under a WhatsApp Business Account. To get this permission, your app must go through App Review.
  • whatsapp_business_messaging — Used to send/receive messages from WhatsApp users, upload/download media under a WhatsApp Business Account. To get access to this permission, reach out to your representative and provide your Facebook app ID.

If you're working as a BSP (Business Solution Provider), feel free to use the same Facebook app across different clients and WABAs. But be aware that each app can only have one webhook endpoint.

System User

See Add System Users to Your Business Manager for help.

Business Phone Number

This is the phone number the business will use to send messages. Businesses must use a test phone number for this release.


Use your existing WhatsApp Manager to add a phone number. Phone numbers need to be verified through SMS/voice call, either through Embedded Signup flow or manual verification. You cannot verify your phone with Graph API.


The verification status of a phone number doesn't impact the migration between On-Premises and Cloud API. If you don't have access to Embedded Signup to verify phone numbers, we recommend verifying the phone numbers using the On-Premises solution, and then migrating those numbers to the Cloud API.

Consumer Phone Number

This is a phone number that is currently using the consumer WhatsApp app. This number will be receiving the messages sent by your business phone number.

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:

  1. Go to Business Manager > Business Settings > Users > System Users to view the system user you created.
  2. Click on that user and select Add Assets. This action launches a new window.
  3. Under Select Asset Type on the left side pane, select Apps. Under Select Assets (in the middle pane), choose the Facebook app you want to use (your app must have the correct permissions). Enable Develop App for that app.
  4. Select Save Changes to save your settings and return to the system user main screen.
  5. Now you are ready to generate your token. Still on the system user main screen, click Generate Token and, again, select your Facebook app. After selecting the app, you see a list of available permissions. Select whatsapp_business_management and whatsapp_business_messaging and click Generate Token.
  6. A new window opens with your system user, assigned app and access token. Save your token.
  7. 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 API. 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.

Once the Webhook is set up, configure it to be used by your Facebook app. For more information, see Configuring the Webhooks Product. Only one application can have one Webhook endpoint configured at any time for a WhatsApp Business Account, so if you’re an existing user of Webhooks, make sure to create a new one for your WhatsApp API integration.

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.

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/v12.0/WHATSAPP_BUSINESS_ACCOUNT_ID/subscribed_apps' \
  -H 'Authorization: Bearer SYSTEM_USER_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/v12.0/WHATSAPP_BUSINESS_ACCOUNT_ID/phone_numbers' \
 -H 'Authorization: Bearer SYSTEM_USER_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.

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:

  1. Register the phone.
  2. 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/v12.0/FROM_PHONE_NUMBER_ID/register' \
  -H 'Authorization: Bearer SYSTEM_USER_ACCESS_TOKEN' \
  -d '{
    "messaging_product": "whatsapp",
    "pin": "6_DIGIT_PIN"
  }'

Sample response:

{
  "success": "true"
}

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/v12.0/FROM_PHONE_NUMBER_ID/messages' \
  -H 'Authorization: Bearer SYSTEM_USER_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.