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:

ConsiderationMore Context

Are my client’s throughputs and message volumes supported by Cloud API?

The Cloud API supports most businesses at 80 messages/second cumulative peak throughput, including text/media and ingoing/outgoing.

Are my client’s compliance needs met by the Cloud API?

The Cloud API is GDPR compliant and has SOC 2 certification. Servers are hosted in North America.

Are my clients using features supported by the Cloud API?

Most major features are supported. See full list here.

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:

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.

Meta App

If you don’t have an app, you need to create one with the “Business” type. Remember to add a display name and a contact email to your app.


As a BSP (Business Solution Provider), your app must go through App Review and request Advanced Access to 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 this permission, your app must go through App Review.
  • business_management

See a sample App Review submission here.


As a BSP, you can also feel free to use the same Meta app across different clients and WABAs. But be aware that each app can only have one webhook endpoint and each app needs to go through App Review.

System User

See Add System Users to Your Business Manager for help.


Currently, a Meta App with whatsapp_business_messaging, whatsapp_business_management, and business_messaging permissions has access to up to:

  • 1 admin system user, and
  • 1 employee system user

We recommend using the admin system user for your production deployment. See About Business Manager Roles and Permissions for more information.

Business Phone Number

This is the phone number the business will use to send messages. Phone numbers need to be verified through SMS/voice call.


For BSPs and Direct Businesses: If you wish to use your own number, then you should add a phone number in WhatsApp Manager and verify it with the verify endpoint via Graph API.


For Businesses using BSPs: If you wish to use your own number, then you should add and verify their numbers using the BSP’s Embedded Signup flow.


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.

There is no limit to the amount of business phone numbers that can be onboarded to the Cloud API.


A given phone number can only be on one platform at a time: Either on Cloud API or on On-Premises. This means that you cannot use a production phone number on both On-Premises and Cloud API at the same time.

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.

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.

You as a developer need to accept the terms of service. If you are a Business Solution Provider, you do not need your customers to accept.

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:

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/v13.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/v13.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

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:

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

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

WhatsApp develops and operates the WhatsApp Business API, which enables businesses to communicate with WhatsApp consumer users on the WhatsApp network. When using the Cloud API, Meta will host the WhatsApp Business API for you and provide an endpoint for the WhatsApp service for your incoming and outgoing WhatsApp communications.

No, there is no difference in messaging prices between the Cloud API and the On-Premises API. Access to Cloud API is free, and we expect it to generate additional cost savings for developers. The two types of cost savings for the Cloud API are 1) set up cost (including server or external cloud provider cost), 2) ongoing cost of maintenance (including engineering time for API upgrades).

A Business Solution Provider can select which setup a given client should use. We recommend that the majority of clients use the Cloud API for ease of implementation and maintenance. Business Solution Providers can also continue to maintain integration with the on-premises API.

We want to make it clear what it means to message with a business on WhatsApp. Some businesses may choose to use Meta or another company to help them manage and store their messages. When a business chooses to manage their messages with another company, we will let consumers know by showing a different system message. Learn more.

We expect Cloud API to provide the same following key features as the On-premises API soon, including single and multi-product messages, user change notifications, and sticker pack management. Our goal is for the Cloud API to become the preferred platform for new features.

We will release updates monthly with new features and improvements. There is no work required to access these features - the Cloud API updates automatically.

No, we will continue to provide the On-Premises API for now. See On-Premises API for information.

Technical Implementation FAQs

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.

BSPs and direct clients do not need the WebApp and CoreApp containers that are used in the On-Premises product. Meta will manage all database data and media data on behalf of the BSP or direct client.

We will have disaster recovery and data replication across multiple regions. The expected downtime would be within our SLA and usually in the order of less than a minute to less than five minutes. We will share more information on SLAs in 2022.

As your on-premises performance depends heavily on your hardware, software, and connectivity to WhatsApp servers, if you wish to understand these differences, you can perform your own load tests on Cloud API as you might have done for your own on-premises installation. You can also refer to our performance comparison to understand more details around how the on-premise and Cloud APIs compare.

Data Privacy & Security FAQs

Cloud API runs in the Meta data centers. Meta has data centers in North America and the E.U. At this time, we do not offer data localization.

Messages at rest are encrypted. They are automatically deleted after 30 days.

Like all other WhatsApp Business API Business Solution Providers, Meta manages the encryption and decryption keys on behalf of the business. In order to send and receive messages through Cloud APIs, Cloud API software manages the encryption/decryption keys on behalf of the business. Meta will operate the Cloud API and its terms limit its use of providing this service to delivering messages only. WhatsApp does not have access to keys nor messages.

Regulatory Compliance FAQs

Meta takes data protection and people's privacy very seriously and we are committed to continuing to comply with data protection laws. The Cloud API allows our customers to continue to meet their obligations under General Data Protection Regulation (GDPR). Meta complies with applicable legal, industry, and regulatory requirements as well as industry best practices. See more.