Cloud API

Overview

Cloud API, hosted by Meta, allows medium and large businesses to communicate with customers at scale. Using the API, businesses can build systems that connect thousands of customers with agents or bots, enabling both programmatic and manual communication. Additionally, businesses can integrate the API with numerous backend systems, such as CRM and marketing platforms.

HTTP Protocol

Cloud API is built on Graph API, so requests are expressed using the HTTP protocol and combinations of URL parameters, headers, and request bodies. For example, a common call to Cloud API from UNIX-based command line looks like this:

curl 'https://graph.facebook.com/v17.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505555555",
  "type": "text",
  "text": {
    "preview_url": true,
    "body": "Here'\''s the info you requested! https://www.meta.com/quest/quest-3/"
  }
}'

If you are unfamiliar with Graph API, refer to our Graph API documentation to learn the basics. The main differences between Graph API and Cloud API are which access token types you will commonly be using, resource permissions, request syntax, and webhooks syntax. These differences are described in further detail in appropriate sections of the Cloud API documentation set.

Resources

These are the primary resources you will be interacting with when using the API.

Business Portfolio

To use the API, you must have a business portfolio. If you do not have a portfolio, you will be prompted to create one as part of our Get Started process. Business portfolios serve as a container for your WhatsApp Business Account (WABA) and business phone numbers.

To learn more about business portfolios, see our About business portfolios in Meta Business Suite help center article.

WhatsApp Business Accounts

A WhatsApp Business Account represents a business on the WhatsApp Business Platform and is composed primarily of metadata about a specific business. Most other WhatsApp resources, such as WhatsApp Business Phone Numbers and WhatsApp Message Templates are associated with a WABA.

You can create a WABA by following the steps in our Get Started document. To learn more about WABAs and their limitations, see WhatsApp Business Accounts.

WhatsApp Business Phone Numbers

A WhatsApp Business Phone Number (business phone number) represents a real phone number, which, once registered for use with Cloud API, can be used to send and receive messages to and from WhatsApp users via the API.

Business phone numbers are composed mostly of metadata about the number itself and your business, and this metadata can be surfaced in the WhatsApp client when users interact with your business phone number.

You can create a business phone number by following the steps in our Get Started document. Note that there are restrictions and limitations on business phone numbers and their uses, which are described in detail in our Business Phone Numbers document.

WhatsApp Message Templates

WhatsApp Message Templates (template) are customizable templates that you can construct via the API using various template components. Once created, they are automatically reviewed, and if approved, can be used in template messages.

There are two basic types of messages that you can send via the API: free-form messages and template messages. Of the two, template messages are the most restrictive, since they require the use of an approved WhatsApp Message Template. However, since templates must undergo review and be approved before they can be used, template messages are less likely to receive negative feedback from recipients, which can jeopardize your ability to message customers entirely.

To learn more about templates, refer to our Templates document.

Webhooks

Webooks are simply JSON payloads sent using the HTTP protocol to a public endpoint on your server. Cloud API relies heavily on webhooks, as the contents of any messages sent from a WhatsApp user to your business phone number will be sent as a webhook, and all outgoing message delivery status updates are reported via webhook.

Note that we do offer a sample webhook app that you can clone on Glitch and use for testing. The app just dumps webhooks payloads directly to a console so you can see their contents. Keep in mind that you eventually need to build your own endpoint on your own server at some point which digests webhooks according to your own business logic.

See Meta Webhooks to learn more about webhooks and how to digest them, and our Webhooks for WhatsApp Business Accounts document.

Test Resources

When you first complete the steps in our Get Started document, a test WABA and test business phone number are automatically created for you.

Test WABAs and test phone numbers are useful for testing purposes, as they bypass most messaging limits and don't require a payment method on file in order to send template messages.

You can delete your business portfolio and its test resources if:

  • you are an admin on the business portfolio associated with the app
  • no other apps are associated with the business portfolio
  • the business portfolio is not associated with any other WABAs
  • the WABA is not associated with any other business phone numbers.

To delete your business portfolio and its test resources:

  1. Go to the App Dashboard > WhatsApp > Configuration panel.
  2. Locate the Test Account section.
  3. Click the Delete button.

Authentication and Authorization

Access Tokens

The API supports three types of tokens:

  • System User Access Tokens
  • Business Integration System User Access Tokens
  • User Access Tokens

See our Access Tokens to determine which type of token you should use. Note that tokens should be passed via request headers, not as a query string parameter.

Permissions

The API relies on the following Graph API permissions. The exact combination of permissions your app needs depends on which endpoints your app will be accessing.

  • business_management — needed if interacting with a business portfolio.
  • whatsapp_business_management — needed if interacting with a WABA and its analytics, or any of its templates or business phone numbers.
  • whatsapp_business_messaging — needed to send and receive messages to and from WhatsApp users.

These permissions are typically granted when generating access tokens in the Meta Business Suite. See the token generation sections in our Access Tokens document.

Versioning

Versioning uses Graph API's versioning protocol. This means that all endpoint requests can include a version number, and each version will be available for roughly 2 years before it will be retired and can no longer be called.

Throughput

For each registered business phone number, Cloud API supports up to 80 messages per second (mps) by default, and up to 1,000 mps by automatic upgrade.

Throughput is inclusive of inbound and outbound messages and all message types. Note that business phone numbers, regardless of throughput, are still subject to their WhatsApp Business Account's business use case rate limit and template messaging limits.

If you attempt to send more messages than your current throughput level allows, the API will return error code 130429 until you are within your allowed level again. Also, throughput levels are intended for messaging campaigns involving different WhatsApp user phone numbers. If you attempt to send too many messages to the same WhatsApp user number, you may encounter a pair rate limit error.

Higher Throughput

If you meet our eligibility requirements, we will automatically upgrade your business phone number to 1,000 mps at no cost to you. Higher throughput does not incur additional charges or affect pricing.

The upgrade process itself can take up to 1 minute. During this time the number will not be usable on our platform. If used in an API request, the API will return error code 131057. Once a business phone number has been upgraded, it will automatically be upgraded for any future throughput increases with no downtime.

Eligibility Requirements

Webhooks

Your webhook servers should be able to withstand 3x the capacity of outgoing message traffic and 1x the capacity of expected incoming message traffic. For example, if sending 1,000 mps with a 30% expected response rate, your servers should be able to process up to 3000 message status webhooks plus an additional 300 incoming message webhooks.

We attempt to deliver webhooks concurrently, so we recommend you configure and load test your webhook server to handle concurrent requests with the following latency standard:

  • Median latency not to exceed 250ms.
  • Less than 1% latency exceeds 1s.

We will attempt to re-deliver failed webhooks for up to 7 days, with exponential backoff.

Media Messages

To take full advantage of higher throughput, we recommend that you upload your media assets to our servers and use the returned media IDs in media messages instead of hosting the assets on your own servers and using media asset URLs. If you prefer (or must) host the assets on your own servers, we recommend that you use media caching.

Getting Throughput Level

Use the WhatsApp Business Phone Number endpoint to get a phone number's current throughput level:

GET /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>?fields=throughput

Migration

If you migrate a business phone number that has multiconnect running 2 or more shards from On-Premises API to Cloud API, it will automatically be upgraded to higher throughput.

Rate Limits

See WhatsApp Business Management API rate limits.

In addition to these rate limits, we have more granular limits on individual resources such as template messages and test business phone numbers:

Available Metrics

As a Cloud API user, you can see the number of messages sent and delivered, as well as other metrics. See Get Account Metrics for information.

Scaling

Within Meta's infrastructure, the Cloud API automatically scales and adjusts to handle your workload, within your rate limit (messaging volume and number of WABAs).

Data Privacy & Security

See our Privacy & Security Overview for information.

Encryption

With the Cloud API, every WhatsApp message continues to be protected by Signal protocol encryption that secures messages before they leave the device. This means messages with a WABA are securely delivered to the destination chosen by each business.

The Cloud API uses industry standard encryption techniques to protect data in transit and at rest. The API uses Graph API for sending messages and Webhooks for receiving events, and both operate over industry standard HTTPS, protected by TLS. See our Encryption Overview whitepaper for additional details.

See our Encryption Overview whitepaper for additional details.

Pair Rate Limits

Business phone numbers are limited to sending 1 message every 6 seconds to the same WhatsApp user phone number (0.17 messages/second). This is roughly equivalent to 10 messages per minute, or 600 messages per hour. If you exceed this limit, the API will return error code 131056 until you are within your limit again.

If necessary, you can send up to 45 messages within 6 seconds as a burst. If you send a burst, you are essentially borrowing against your pair rate limit, so you will be prevented from sending subsequent messages to the same user until the amount of time it would normally take to send that many "non-burst" messages to the user has passed. For example, it takes ~2 minutes to send 20 "non-burst" messages to a user, so if you send a burst of 20, you will have to wait ~2 minutes before you can send another message to the user.

To avoid having to calculate post-burst message wait times, we recommend that if a message send request fails after sending a burst, you try again 4^X seconds later, where X = 0, and increases by 1 after each failed attempt, until the request succeeds.

Tools

WhatsApp Manager

The WhatsApp Manager is our web app that allows you to manually manage WhatsApp resources, such as WABAs, business phone numbers, and templates, and provides an easy way to see insights and quality ratings or limits on these resources. Most functionality offered by the WhatsApp Manager is also available via the API, with a few minor exceptions.

There are several ways to access the WhatsApp Manager. Each path assumes you have already completed all steps in our Get Started document.

Via the Meta Business Suite

  1. Log into the Meta Business Suite.
  2. If you have multiple business portfolios, use the dropdown menu on the left to select the account that owns, or has access to, the WABA you wish to load in the WhatsApp Manager.
  3. In the menu on the left, navigate to Accounts > WhatsApp Accounts.
  4. Select the WABA.
  5. In the Summary tab, click the WhatsApp Manager button.

Via the App Dashboard

  1. Go to My Apps.
  2. Select the app that is associated with the WABA you want to load in the WhatsApp Manager.
  3. In the menu on the left, navigate to WhatsApp > Quickstart.
  4. Click the Account information tile in the WhatsApp Business section.

Via URL

You can go directly to the WhatsApp Manager Overview, which displays all of the WABAs owned by, or shared with, a given business portfolio, by visiting:

https://business.facebook.com/wa/manage/home/

By default, the overview loads the most recent WABA you created or were granted access to, but you can use the dropdown menu on the left to select the business portfolio that contains the WABA you are trying to access . This will take you out of the overview, however, and you must then use the menu on the left and navigate to Accounts > WhatsApp Accounts > (select the desired WABA) > Settings > WhatsApp Manager (button).

Alternatively, if you have multiple business portfolios, you can append an account's ID to the end of the URL and bookmark it for easier access:

https://business.facebook.com/wa/manage/home/?business_id=<META_BUSINESS_ACCOUNT_ID>

Postman

We have a Cloud API Postman collection containing common queries in our WhatsApp Business Platform workspace.