Overview

The WhatsApp Business API allows medium and large businesses to communicate with their 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, you can integrate the API with numerous backend systems, such as CRM and marketing platforms.

Businesses looking to use the API have two hosting options: On-Premises and Cloud API. In general, we recommend that the majority of businesses use the Cloud API due to ease of implementation and maintenance.

To use the Cloud API, businesses make calls to Meta’s Graph API to send messages and Webhooks to receive events, such as messages and status updates. The Graph API is a form of Remote Procedure Call expressed over HTTP, where operations and their parameters are expressed using a combination of URL parameters, headers, and request body.

A call to the Graph API from UNIX-based command lines looks like this:

curl -X POST \
  'https://graph.facebook.com/v17.0/FROM_PHONE_NUMBER_ID/messages' \
  -H "Authorization: ACCESS_TOKEN" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "1650XXXXXXX",
    "text": {"body" : "hi"}
   }'

Compared to the On-Premises implementation, a Graph API integration relies on a different authentication mechanism (see User Access Token), a different Webhook setup process (see Setup Webhooks), and has different latencies and error rates. For more information on how to use the Graph API, see the Graph API Developer Documentation.

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

The Cloud API supports up to 80 messages per second (mps) by default and up to 1,000 mps by request. Throughput is inclusive of inbound and outbound messages and all message types.

How to request 1,000 mps

You can request 1,000 mps for specific phone numbers by opening a Direct Support ticket with the following selections:

• Question Topic: Cloud API Issues
• Request Type: Request to upgrade to high throughput tier

After you submit your ticket a WhatsApp representative will contact you with instructions, schedule an upgrade time, and support you throughout the upgrade process. Scheduling and approval can take up to a week, so we recommend that you request 1,000 mps at least one week before you need it.

Configuration timelines differ depending on the migration path. After approval from a WhatsApp engineer, you can expect the following business phone number downtimes:

• New to Cloud API: No downtime (Instant upgrade)
• Existing high throughput client: No downtime (Instant upgrade) *
• Existing On-Premise API to high throughput on Cloud API: 5 minutes downtime
• Existing Cloud API to high throughput on Cloud API: Up to 1 hour if done over the phone, or longer if done over email

* Existing high throughput phone numbers do not need to request for throughput upgrades. Once a business phone number has been upgraded it will automatically be upgraded for any future throughput increases.

Migration Considerations

If you are migrating a business phone number from On-Premises API to Cloud API and you also want higher throughput for that number, request 1,000 mps before migrating the number.

Webhooks

Your webhook servers should be able to withstand 3x the capacity of outgoing message traffic. For example, if sending out 1,000 mps, it is possible to receive over 3,000 events per second of receiving notifications.

Media Messages

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

Rate Limits

Cloud API follows Business Use Case Rate Limits. Each WhatsApp Business Account (WABA) has a call count rate limit and each call made by your app counts toward the limit. An app’s call count for a WABA is the number of calls it can make to business accounts under this WABA during a rolling one hour window and is calculated as follows:

Calls within one hour for a WABA = 1800000 * Number of Registered Numbers under this WABA

You will receive an error code 80007 when you hit call limits.

Besides platform rate limits, we have the following rate limits applicable to Cloud API accounts:

• Test message rate limit: Applies to unverified WhatsApp Business Accounts.
• Quality rating and messaging limits: Applies to verified WhatsApp Business Accounts.
• Capacity rate limit: Applies to all accounts.
• Business phone rate limit: Applies to all accounts and limits the throughput per business phone number.

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 WhatsApp business accounts).

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 WhatsApp business account 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.

On-Premises API vs. Cloud API Comparison

Key Differences

Deprecations

The Check Contacts and the Media Provider APIs are still in use for the On-Premises API, but they have been deprecated with the Cloud API. See more information below: