Get Started for Business Solution Providers

This guide goes over the steps Business Solution Providers (BSP) need to take in order to offer the Cloud API to their customers. There are 4 main stages:

1. Prepare & Plan
2. Set up Assets
3. Sign Contracts
4. Build Integration

After you’re done, please keep up with monthly updates.

Prepare & Plan

Read Documentation

Before you start, we recommend reading through our developer documentation and our Postman collection. This helps you understand how the Cloud API works, including how to get started and migrate numbers.

Plan Onboarding & Migration

You must use Embedded Signup to onboard new customers to the Cloud API. If you haven’t already, integrate and launch Embedded Signup. Embedded Signup is the fastest and easiest way to register customers, enabling them to start sending messages in less than five minutes.

Next, think about which clients you want to migrate to the Cloud API first. Our general recommendation is to migrate all of your clients from the On-Premises to the Cloud API, but each client’s need may vary. As you think about which clients to migrate, consider:

Once you know who’s going to be migrated, you can build a migration plan and timeline.

As you create your plan, remember to design your system for two scenarios: onboarding new customers and migrating current customers from On-Premises to Cloud API. For the migration scenario, include plans to backup your current On-Premises instance and migrate those numbers to the Cloud API.

Plan Communication With Clients

First, you need to decide whether to notify existing clients about migration. Then, you should determine if you need to create or update any documentation to support the Cloud API setup.

Make Pricing Decisions

Since the hosting costs for the Cloud API are covered by Meta, you should decide if you would like to update your prices accordingly.

Set up Assets

To use the Cloud API, BSPs need to have the following assets:

Sign Contracts

Accepting Terms of Service

In order to access the WhatsApp Business Messaging Cloud API you need to first accept the WhatsApp Business Platform Terms of Service on behalf of your business.

To do so, navigate to WhatsApp Manager and accept the terms of service in the informational banner.

If you are an existing beta partner for the Cloud API you have a grace period of 90 days. This means you need to accept the terms before July 5, 2022 or you will lose access.

For any new Cloud API businesses, including those migrating from the on-premises API, you will need to accept terms of service before you can start using the Cloud API. Registration calls will fail until you accept the terms of service.

Build Integration

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, choose the Meta 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. 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, and business_management. 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 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:

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/v17.0/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/v17.0/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

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. If you do not set it up, you will get an onboarding failure message:

Sample request:

curl -X POST \
'https://graph.facebook.com/v17.0/FROM_PHONE_NUMBER_ID/register' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"messaging_product": "whatsapp","pin": "6_DIGIT_PIN"}'

Sample response:

{
  "success": true
}

Embedded Signup Users

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/v17.0/FROM_PHONE_NUMBER_ID/messages' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-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 through Webhooks. The maximum length of the ID is 128 characters.

Sample response:

{
  "id":"wamid.gBGGFlaCGg0xcvAdgmZ9plHrf2Mh-o"
}

Keep up with Monthly Updates

We will release Cloud API updates on the first Tuesday of every month. Those will include new features and improvements. You don’t need to do any work to use any of the new features, since the Cloud API updates automatically.

FAQs

General FAQs

Technical Implementation FAQs

What is the architecture of the Cloud API?

The Cloud API architecture significantly simplifies the BSP’s operational and infrastructure requirements to integrate with WhatsApp Business Platform. First, it removes the infrastructure requirements to run Business API docker containers (CAPEX savings). Second, it obviates the need of operational responsibilities to manage the deployment (OPEX savings). For details, refer to the architecture diagram comparing the On-Premises and Cloud API deployments.

Permalink

Data Privacy & Security FAQs

Regulatory Compliance FAQs