Skip links

Meta WhatsApp Cloud API Documentation

Meta WhatsApp Cloud API Documentation is a comprehensive resource provided by Meta (formerly Facebook) that offers detailed information and guidelines for developers looking to integrate WhatsApp messaging functionality into their applications and services. This documentation provides essential insights to utilise the WhatsApp Cloud API, enabling seamless communication with WhatsApp users, and unlocking powerful features to enhance user experiences within your digital platforms. Developers can find code examples, best practices, and technical specifications to streamline the integration process, making it easier to leverage the popular WhatsApp messaging platform in their applications.

 

Send and receive messages using a cloud-hosted version of the WhatsApp Business Platform. The Cloud API, hosted by Meta, allows you to implement WhatsApp Business APIs without the cost of hosting of your own servers and also allows you to more easily scale your business messaging.

If you are a developer who wants direct access to the Cloud API to build on the behalf of a client’s business, fill out this form and we will reach out with more information.

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.

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.

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

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 request. 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.

Requesting Higher Throughput

If you are planning a messaging campaign that requires increased throughput, you can request an upgrade to 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

If approved, we will perform the upgrade at the time you specified in your upgrade request. The upgrade process itself can take up to 5 minutes. During this time, the number will not be usable on our platform.

Once a business phone number has been upgraded it will automatically be upgraded for any future throughput increases with no downtime.

Eligibility Requirements

  • The business phone number must be registered for use with Cloud API. If the number is registered for use with On-Premises API, it must be migrated to Cloud API first.

  • The business phone number must have a Medium quality rating or higher.

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

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

Each WhatsApp Business Account (WABA) has a call count rate limit. Each call made by your app to any of a WABA’S business phone numbers (i.e. the WhatsApp Business Account Phone Number node or any of its edges, such as the Messages endpoint) counts against its limit.

The current limit is 11,880,000 calls per rolling-hour for a given WABA.

For example, within a one-hour period, your app could make 11.8M calls using WABA A and another 11.8M calls using WABA B. Or, within a one-hour period, your app could make up to 11.8M total calls using a combination of different numbers owned by a single WABA.

If you reach your limit, the API will respond with error code 80007.

Note that the Business Management API has different 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 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

Key Differences

On-Premises API

Cloud API

Hosting

Individual businesses and/or Solution Partners need to host the API software on their own servers and in data centers.

Meta hosts the API.

Maintenance

Individual businesses and/or Solution Partners need to perform API software upgrades periodically.

API software upgrades are performed by Meta and new features and security updates are available automatically on the Cloud API.



Developers no longer need to do setup, maintenance or scaling work. There will be minimal code changes required to adapt to longer-term API changes.

Costs

Businesses or Solution Partners need to:

  • Pay the costs of setting up and maintaining their servers.

  • Pay per message sent or per conversation, following the rules described here.

Meta pays for the hosting costs.



Businesses only pay per message sent or conversation, per the rules described here.

API Protocol

On-Premises REST API.

Graph API.

Throughput

(Messages Per Second)

Send up to 70 text messages per second for single-connect.



Send up to 250 text messages per second for multi-connect.



Sending media messages may reduce these numbers.

Up to 1,000 messages per second. In the event of high system loads, a business may experience reduced message throughput. See Throughput.

Certificate Management

You manage your Certificate Authority (CA) and Webhook CA certificates.

Meta manages the CA certificates.



For a Webhook CA certificate, your Webhooks server needs to support HTTPS and have a valid CA-chained TLS/SSL certificate installed. Self-signed certificates are not supported.

Media Provider API

Supported.

Deprecated. To upload media to the Cloud API, follow these steps.

Stickerpack Management API

Supported.

Currently not supported.

Disaster Recovery

Business/Solution Partner needs to deploy in “high availability” model.

No SLA.

Single-tenant vs. Multi-tenant

Single-tenant (single phone number per deployment).

Multi-tenant. Multiple phone numbers can be registered on CAPI.

Send Message Request Processing Latency

Dependent on business deployment location (i.e. latency from their infra to WhatsApp infra in North America).

Expect the latency between receiving a request and sending a response on Meta servers to be:

90th percentile: ~1s

99th percentile: ~2s



There is a plan to eventually get to

99th percentile: ~500ms

Server Location

Dependent on business.

North America.

Monitoring Metrics Available

Insights data available.



Businesses are responsible for setting up monitoring of the on-premise solution themselves (monitoring containers included in packaging).

Insights data available.



Meta monitors instance health.

SLA (Uptime)

Not specified because it depends on an end-to-end API solution, which includes the businesses or Solution Partner’s infrastructure.

Ongoing efforts to meet our commercially reasonable goals of 99.9%

Support

7×24 for critical issues on a best effort basis.

7×24 for critical issues. Continuous work until the issue is resolved or mitigated.

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:

On-Premises API

Cloud API

Check Contacts API

For Cloud API, this call is no longer required to send messages. You can just use the person’s phone number.

Media Provider API

To upload media to the Cloud API, follow these steps.








The process of verifying a Facebook business account involves several steps, including creating a business account, providing necessary documents, and waiting for Facebook’s approval. Here’s a step-by-step guide to the full process, along with estimated timelines:

 

Step 1: Create a Business Manager Account

  • Go to Business Manager: Visit the Facebook Business Manager website (business.facebook.com) and log in with your personal Facebook account credentials.
  • Create a Business Manager Account: Click on “Create Account” and follow the prompts to set up your Business Manager account. You will need to provide basic information about your business.
  •  

Step 2: Add Your Business Page

  • Access Business Settings: In Business Manager, go to “Business Settings.”
  • Add a Page: Click on “Pages” in the left sidebar, then click “Add.” Follow the instructions to add your business’s Facebook Page to your Business Manager.
  •  

Step 3: Start Verification

  • Access Business Verification: In Business Manager, go to “Business Settings” and click on “Security Center.”
  • Start Verification: Under “Business Verification,” click “Start Verification.”
  •  

Step 4: Provide Business Details

  • Business Details: Fill in the required information about your business, including your legal business name, address, and phone number. Ensure that this information matches your official business documents.
  •  

Step 5: Verify Domain Ownership

  • Verify Domain: If you have a website, Facebook may ask you to verify domain ownership. This involves adding a provided meta-tag or DNS record to your website’s HTML code or DNS settings.
  •  

Step 6: Submit Documents

  • Document Submission: Facebook may request specific documents to verify your business. The types of documents required may vary depending on your business type and location. Commonly requested documents include:
  • Business license
  • Tax ID
  • Utility bills or official documents showing your business address
  • Articles of incorporation or registration
  • Personal ID (passport, driver’s license) of the business owner or authorized representative
  • Upload Documents: Scan or take clear photos of these documents and upload them to the Facebook Business Manager as per their instructions.

 

Step 7: Wait for Review

  • Review Process: Facebook will review your submitted documents and information. This can take several days to several weeks, depending on the volume of requests and Facebook’s workload.
  • Communication: Facebook may reach out for additional information or clarification during the review process. Keep an eye on your email associated with your Facebook Business Manager account.
  •  

Step 8: Approval or Rejection

  • Notification: Facebook will notify you via email or within the Business Manager about the outcome of your verification request. If approved, you will gain access to additional features and a verified badge on your business page.
  •  

Timeline for Approval Process:

  • Step 1: Creating a Business Manager account can be done within minutes.
  • Step 2: Adding your business page takes a few minutes.
  • Step 3: Starting verification is immediate.
  • Step 4: Providing business details should take a few minutes.
  • Step 5: Verifying domain ownership may take some time, depending on your website setup.
  • Step 6: Document submission can take several days to a few weeks for review.
  • Step 7: The review process itself can take several days to several weeks.
  • Step 8: Approval or rejection notification can occur once Facebook completes its review.
  •  

Please note that these timelines are estimates and can vary depending on various factors, including the complexity of your business and Facebook’s processing times. It’s essential to ensure that you provide accurate and up-to-date information and documentation to expedite the verification process.


If the “Verify” button is not visible in your Facebook Business Manager, you can follow an alternative process by creating a Facebook app through the Facebook Developer account. Here’s a step-by-step guide:

Step 1: Create a Facebook Developer Account

  • Go to the Facebook Developer website: Visit the Facebook Developer website at https://developers.facebook.com/.
  • Log In or Sign Up: Log in with your personal Facebook account credentials or create a new Facebook Developer account if you don’t have one.
  •  

Step 2: Create a New App

  • Access the Developer Dashboard: Once logged in, you’ll be taken to the Developer Dashboard.
  • Create a New App: Click on the “Create App” button and select “For Everything Else.”
  • App Configuration: Fill in the required fields for your app, including the app name, email address, and a contact email.
  •  

Step 3: Configure Basic Settings

  • Access App Settings: In your app’s dashboard, go to “Settings” in the left-hand menu.
  • Basic Settings: Under “Basic,” configure the necessary settings such as the Privacy Policy URL, Terms of Service URL, and App Icon. Make sure you have a valid Privacy Policy and Terms of Service page accessible online.
  •  

Step 4: Add Products

  • Add Products: In your app’s dashboard, click on “Add a Product” and select “Business Verification.”
  • Configure Business Verification: Follow the prompts to configure Business Verification for your app.
  •  

Step 5: Provide Business Information

  • Business Details: You will be asked to provide information about your business, including your legal business name, address, and phone number. Ensure this information matches your official business documents.
  • Verify Domain Ownership: Similar to the previous process, you may be asked to verify domain ownership by adding a provided meta-tag or DNS record to your website’s HTML code or DNS settings.
  •  

Step 6: Submit Documents

  • Document Submission: Facebook may request specific documents to verify your business. The types of documents required may vary depending on your business type and location. Commonly requested documents include:
  • Business license
  • Tax ID
  • Utility bills or official documents showing your business address
  • Articles of incorporation or registration
  • Personal ID (passport, driver’s license) of the business owner or authorized representative
  • Upload Documents: Scan or take clear photos of these documents and upload them to the Facebook Developer platform as per their instructions.
  •  

Step 7: Wait for Review

  • Review Process: Facebook will review your submitted documents and information. This can take several days to several weeks, depending on the volume of requests and Facebook’s workload.
  • Communication: Facebook may reach out for additional information or clarification during the review process. Keep an eye on your email associated with your Facebook Developer account.

Step 8: Approval or Rejection

  • Notification: Facebook will notify you via email or within the Developer platform about the outcome of your verification request. If approved, you will gain access to additional features and a verified badge on your business page.

Timeline for Approval Process:

  • Step 1: Creating a Facebook Developer account can be done within minutes.
  • Step 2: Creating a new app takes a few minutes.
  • Step 3: Configuring basic settings should take a few minutes.
  • Step 4: Adding products and configuring Business Verification can be completed in a few minutes.
  • Step 5: Providing business information and verifying domain ownership may take some time, depending on your website setup.
  • Step 6: Document submission can take several days to a few weeks for review.
  • Step 7: The review process itself can take several days to several weeks.
  • Step 8: Approval or rejection notification can occur once Facebook completes its review.
  •  
  •  

This guide helps you get started with Cloud API and is intended for people developing for themselves or their organization, not on behalf of a client. If you’re developing on behalf of a client, see this form. All developers must follow our WhatsApp’s Commerce Policy.

To send and receive a first message using a test number, complete the following steps:

  1. Set up developer assets and platform access

  2. Send a test message

  3. Configure a Webhook

  4. Receive a test message

     

Once you’re ready to use your app for a production use case, check the Next Steps section.

1. Set up Developer Assets and Platform Access

 

The Cloud API and Business Management API are part of Meta’s Graph API, so you need to set up a Meta developer account and a Meta developer app. To set that up:

From the App Dashboard, click on the app you would like to connect to WhatsApp. Scroll down to find the “WhatsApp” product and click Set up.

Next, you will see the option to select an existing Business Manager (if you have one) or, if you would like, the onboarding process can create one automatically for you (you can customize your business later, if needed).

Make a selection and click Continue. This will:

  1. Associate your app with the Business Manager account that you selected earlier (or had created for you).

  2. Generate a WhatsApp Business Account.

  3. Generate a test business phone number and associate it with your WhatsApp Business Account. You can use this number with the API to send an unlimited number of messages to up to 5 recipient phone numbers. Recipient phone numbers can be any valid number, but you must verify each one in the next step.

  4. Redirect you to the WhatsApp > API Setup panel in the App Dashboard.

     

2. Send a Test Message

 

In the WhatsApp > API Setup panel:

  1. Select your test phone number in the From field.

     

  2. Enter the recipient phone number you would like to message in the To field. Ensure the number is correct, and that you want to add it to your list of 5 possible message recipients —as you add phone numbers, follow the prompts on the screen to verify you have access to them. Once this number has been added, it cannot be removed from your list. Note: This limitation is only for WhatsApp-provided test phone numbers. Real phone numbers that you register do not have a limit on the number of recipients.

     

  3. Once you enter a recipient phone number, the code sample on the page will be updated to demonstrate an API call that sends a pre-approved message template to that number. Message templates are the only type of message that can be sent to customers who have yet to message you, or have not messaged you in the last 24 hours. Thus, message templates are primarily used to open marketing, utility, and authentication conversations with customers.

  4. The updated code sample will look something like this:curl -i -X POST \
      https://graph.facebook.com/v18.0/105954558954427/messages \
      -H ‘Authorization: Bearer EAAFl…’ \
      -H ‘Content-Type: application/json’ \
      -d ‘{ “messaging_product”: “whatsapp”, “to”: “15555555555”, “type”: “template”, “template”: { “name”: “hello_world”, “language”: { “code”: “en_US” } } }’

     

  5. Finally, click Send message to send the first message. As an alternative, you can copy the code sample provided and execute it in your Terminal or in Postman. You have just sent a test message!


The code sample on the page is formatted for use in Unix-style terminal shells, and is expected to work on MacOS and distributions of Gnu/Linux. If you use Windows, we suggest you perform your first API call using Postman, to avoid platform-related cURL formatting concerns. If you are a Windows 10 user, cURL is available, but requires a different syntax than the one shown in the panel to execute in PowerShell or cmd.exe. For more information, see cURL Comes to Windows or cURL for Windows. If you have access to the Windows Subsystem for Linux (WSL), you can also consider launching a Linux distribution and using its terminal.

3. Configure a Webhook

 

To get alerted when you receive a message or when a message’s status has changed, you need to set up a Webhooks endpoint for your app. Setting up Webhooks doesn’t affect the status of your phone number and does not interfere with you sending or receiving messages.

To get started, first you need to create the endpoint. You can create a custom Webhook URL running on a web server, or use services that help you set up an endpoint, such as Glitch. See Create a Sample App Endpoint for Webhooks Testing for help.

Once your endpoint is ready, go to your App Dashboard.

In the App Dashboard, go to WhatsApp > Configuration, then click the Edit button.

  • 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.

After saving, back in the Configuration panel, click the Manage button and subscribe to individual webhook fields. To receive notifications of customer messages, be sure to subscribe to the messages webhook field.

4. Receive a test message

 

Now that your Webhook is set up, send a message to the test number you have used. You should immediately get a Webhooks notification with the content of your message!


Next Steps

 

Phone Number

 

When you’re ready to use your app for a production use case, you need to use your own phone number to send messages to your users. When choosing a phone number, consider the following:

  • If you want to use a number that is already being used in the WhatsApp customer or business app, you will have to fully migrate that number to the business platform. Once the number is migrated, you will lose access to the WhatsApp customer or business app. See Migrate Existing WhatsApp Number to a Business Account for information.

  • We have a set of rules regarding numbers that can be used in the platform. Learn more .

  • Once you have chosen your phone number, you have to add it to your WhatsApp Business Account. See Add a Phone Number .

     

Opt-In

 

You are required to obtain user opt-in before opening marketing, utility, and authentication conversations with customers.

Pricing & Payment Methods

 

Businesses are charged per conversation, which includes all messages delivered in a 24 hour session. The first 1,000 Service conversations each month are free. If you want to have more than 1,000 Service conversations, you must add a credit card to your account

If you’re a developer who is developing for yourself or your organization, not on behalf of a client, you may add a credit card to your WhatsApp Business account. To set up a credit card as a payment method, go to App Dashboard > WhatsApp > Configuration. Under Phone numbers, click Manage phone numbers. This leads you to your Business Manager account, where you can click Add Payment Method to add your credit card. Currently only Visa and Mastercard are supported.

There are six currencies available for payment: USD, AUD, EUR, GBP, IDR, INR. Credit card payment method is available if you’re located in any of the countries listed in the Business Manager Supported Countries for WhatsApp Business Credit Card Billing help center article.

For more information, see Add a Credit Card to Your WhatsApp Business Platform Account .

Scale Conversations

 

To be able to open more marketing, utility, and authentication conversations, you need to use message templates. WhatsApp message templates are specific message formats that businesses use to send out notifications or customer care messages to people that have opted in to notifications.

Before sending a message template, you need to create one or you can use one of our pre-approved templates. Check this guide to learn how to send message templates.

Incoming messages are unlimited, but there are limits for outgoing messages. See Messaging Limits for more information on messaging tiers.

  •  
  • Overview

     

    The Business Management API allows you to create and manage WhatsApp-related business assets, such as WhatsApp Business Accounts and message templates. The API is built on the Marketing API and leverages some of its endpoints, so this documentation may contain links to the Marketing API documentation where appropriate.

    Requirements

     

    System Users

    System users can be used to generate System User Access Tokens, which are typically what you will be using in API requests. Most endpoints check if the user identified by the token has access to the queried resource. If the user does not have access to the resource, the request will be rejected with error code 200.

    If your app will be accessing WhatsApp Business Accounts and assets shared with your business, we recommend creating an admin system user. If your app will only be accessing data owned by your business, either type is sufficient.

    To create a system user:

    1. Sign into the Meta Business Suite.

    2. Locate your business account in the top-left dropdown menu and click its Settings (gear) icon.

    3. Click Business settings.

    4. Navigate to Users > System users.

    5. Click the Add button and create either an admin or employee system user.

       

    Admin System Users

     

    By default, admin system users have full access to all WhatsApp Business Accounts and assets owned by, or shared with, the Meta business.

    Admin system users are useful if your app needs to access WhatsApp Business Accounts that are newly shared with your business; if you are using an employee system user, you must manually grant access to each WhatsApp Business Account that has been shared with you.

    Note that you can override an admin system user’s default access by granting partial access on a per-WhatsApp Business Account basis.

    Employee System Users

     

    Employee system users must be granted access to individual WhatsApp Business Accounts that are owned by, or shared with, the Meta business. If your app will only need access to a few WhatsApp Business Accounts that you own, an employee system user should be sufficient.

    Once created, you must grant full or partial access to each WhatsApp Business Account that the system user needs to access.

    System User Access Tokens

     

    We recommend that you use system user access tokens to access the Business Management API and Cloud API. To generate a System User access token after creating a system user:

    1. Sign into the Meta Business Suite.

    2. Locate your business account in the top-left dropdown menu and click its Settings (gear) icon.

    3. Click Business settings.

    4. Navigate to User > System users.

    5. Select the appropriate system user from the list of system users.

    6. Click the Generate new token button.

    7. Select the app that will use the token.

    8. Select any permissions the app needs to function properly and generate the token.

    Include your token in an authorization request header, preceded by Bearer. For example:

    curl -L ‘https://graph.facebook.com/v18.0/102290129340398/‘ \
    -H ‘Authorization: Bearer EAAJB…’

     

    User Access Tokens

     

    Although user access tokens are supported, we recommend that you use system user access tokens to access the Business Management API and Cloud API unless you are implementing Facebook Login.

    WhatsApp Business Account Access

     

    Many endpoints require the user whose token is included in API requests to also be granted partial or full access to the WhatsApp Business Account being queried (or its assets). If the user does not have access, the API will return error code 200.

    Granular access can be set for any user, including system users. Granular access for system users can be useful if you want to restrict access to certain assets for groups of people. For example, if you have a large business and want a certain department to only have read access to a WhatsApp Business Account’s template and business phone number data, you could create a system user for that department and set granular access to view only.

    To designated user access on a WhatsApp Business Account or its assets:

    1. Sign into the Meta Business Suite.

    2. Locate your business account in the top-left dropdown menu and click its Settings (gear) icon.

    3. Click Business settings.

    4. Navigate to Accounts > WhatsApp Accounts.

    5. Select the appropriate WhatsApp Business Account.

    6. Select the WhatsApp Account Access tab.

    7. Click the +Add people button.

    8. Select the appropriate system user and assign appropriate access levels on the WhatsApp Business Account.

     

Create an App

The app creation flow gathers the minimum amount of information needed to generate a unique ID for your app. Once you complete the flow you will end up in the App Dashboard where you can provide additional information about your app, or start building and testing right away.

Before You Start

  • You must be logged into your Meta developer account.

  • Ensure you have not exceeded your app limit. As a Developer, you are permitted to have a developer or administrator role on a maximum of 15 apps. This limit applies to your apps not already linked to a Meta Verified Business. If you have reached the app limit and are unable to create an application or accept a new pending role, take the following steps:

  • Visit your My Apps page to remove any apps you no longer use. You can remove an app entirely or resign your role as an administrator or developer from the app.

  • Archived apps count towards the app limit; if you no longer require these apps, we suggest removing them.

  • If you have already gone through Meta Business Verification, link any unlinked applications to that verified business.

  • If you have not gone through Meta Business Verification and are eligible, please follow the steps to get your business verified.

  • To check if your app is linked to a verified business, check under Basic Settings -> Verifications -> Business verification.

Step 1: Start the app creation process

If you just came from the registration flow, click the Create First App button.

Welcome to Meta for Developers modal with Create First App button.

Otherwise, go to the Apps panel and click Create App.

Apps panel at developers.facebook.com/apps with Create App button.

Step 2: Choose a use case

Your use case determines which permissions, products and APIs are available to your app.

Select a use case and click Next.

If you would like to add Facebook Login for Business, as well as create apps to track ads and manage your business, select the Other option when creating your app.

If you select Other, meaning you want to implement ads, gaming, or messaging, perhaps in addition to Facebook Login, you’ll be redirected to our App Types creation flow (see below).

Step 3: Set your app name and email

Enter the name of your app and an email address where we can send you any important developer notifications. The email address can be different from the email address associated with your Facebook account, just make sure it’s valid and that you monitor it, since all important developer notifications will be sent there. You can also add a Meta Business Account if you have one, then click Create App.

Once you have completed the app creation flow, your app will be loaded in your app dashboard. The app dashboard allows you to view, add, and update details, such as app settings, roles, and additional use cases. You can also request access to the permissions your app will need to make successful API calls to Graph API endpoints for your use cases.

App Type Creation Flow

If you need to implement more products, such as ads, games, or messaging, in addition to Facebook Login or you do not need Facebook Login, you will select an app type during the app creation flow instead of a use case.

Step 1. Choose an app type

Your app type determines which products and APIs are available to your app. If this is your first time creating an app and you are just exploring the app creation flow, choose the None option. Later, when you are more familiar with our products and APIs, refer to our app types document to determine which app type is best suited for your app, then create a new app and choose an appropriate type.

Step 2. Set your app name and email

Enter the name of your app and an email address where we can send you any important developer notifications. The email address can be different from the email address associated with your Facebook account, just make sure it’s valid and that you monitor it, since all important developer notifications will be sent there.

You can also add a Meta Business Manager account if you have one, then click Create App.

Screenshot of name, email, and Business Manager account modal.

Once you have completed the app creation flow your app will be loaded in the App Dashboard.

Screenshot of a newly created app in the App Dashboard.

Next Steps

Now that you have created your app you can add secondary use cases related to your login experience or start building and testing. You can also explore the App Dashboard and provide additional information about your app, but it’s not necessary to start building. You can always return the dashboard and adjust settings and add secondary use cases as they are needed.

Solution Partner and businesses directly integrated with the WhatsApp Business Platform can migrate a registered phone number from one WhatsApp Business Account (WABA) to another. Migrated phone numbers keep their display name, quality rating, messaging limits, Official Business Account status, and any High quality message templates previously approved.

In practice, migration means that a business can keep the same phone number if:

  • They are using the platform with one of our Solution Partners and want to switch to a different provider.

  • They are using their own implementation and want to switch to a Solution Partner.

Only Solution Partners and businesses directly integrated with the WhatsApp Business Platform can perform the phone number migration.

 

Overview

The migration process involves 3 main assets:

 

A source WABA

A phone number

A destination WABA

The account the phone number is currently registered to.

The number that will be migrated.

The account the number will be migrated to.

Phone migration is always initiated by the Solution Partner or business that owns the destination WABA.

WABAs are accounts created inside a business on Business Manager. Each business has an ID — that ID is also commonly known as Business Manager ID.

Both source and destination WABAs can be associated with businesses in two different ways:

U,{bf2057a9-b7f5-4c03-8eaa-1873c829feca}{64},3.125,3.125U,{bf2057a9-b7f5-4c03-8eaa-1873c829feca}{65},3.125,3.125


How Migration Works

Downtime

Until migration is completed by registering the phone number on the destination WABA, the source WABA can continue to send and receive messages without disruption in service. After migration is complete, the destination WABA can start sending messages immediately, without any downtime.

Message Templates

All high quality message templates in the source WABA will be duplicated and automatically approved in the destination WABA as long as the destination WABA can accommodate new templates. Existing message templates in the destination WABA will not be affected. Low quality, rejected, or pending templates will not be duplicated.

If the destination WABA cannot accommodate all of the new templates, we will duplicate as many as we can until the destination WABA’S template limit has been reached. Unduplicated templates must be re-created and submitted for approval if they are to be used by the destination WABA.

Billing Migration

Messages sent before migration are charged to the source business. Messages sent after migration are charged to the destination business. Messages sent from the source, and are not delivered before migration, are still charged to the source business when they get delivered.

Rate Limits

Standard Graph API rate limits apply to the migration.

Limitations

  • Test business phone numbers issued by WhatsApp cannot be migrated.

  • Business phone numbers in use with the WhatsApp Business App cannot be migrated using this process. To migrate a number from the WhatsApp Business app, see Migrating an Existing Number for On-Premises API and Migrating an Existing Number for Cloud API.

  • Message and chat history are not migrated with this process.

  • The API does not support bulk migration; business phone numbers must be migrated individually.

Summary

Migrated

  • Display name

  • Quality rating

  • Messaging limits

  • Official Business Account status

  • Any High quality message templates previously approved

            Not Migrated

  • Low quality, rejected, or pending message templates.

Before You Start

To be eligible for migration, a business’ assets must meet the following criteria:

Asset

Requirements for Migration

Phone number

The phone number’s owner is responsible for reaching out to the source WABA’s owner.

Source WABA

  • Must have Business Verification completed and approved.

  • WABA’s review status must be Approved.

Destination WABA

  • Must have Business Verification and WABA review completed and approved.

  • Must have a payment method set up.

  • Must message on behalf of the same business as the source WABA.

  • Must represent the same business as the source WABA, meaning: the ID of the business that owns the source WABA or the ID of the business that the source WABA is messaging for must match the ID of the business that owns the destination WABA or the ID of the business that the destination WABA is messaging for.

Webhooks

Phone numbers on Cloud API only

At least one app must be subscribed to webhooks for the destination WABA. See Webhooks in Cloud API.


Permissions

All API calls for phone migration must be made with an application that has whatsapp_business_management permission. See Using The WhatsApp Business Management API section to learn more about App Review, Access Tokens, and making API calls. Phone migration is always initiated by the Solution Partner or business that owns the destination WABA.



Preparing the Destination WABA

The type of destination WABA determines what needs to be done for the account to be ready for migration:

Type of WABA

Considerations for Solution Partners performing migration

Existing WABA

Confirm that the existing (destination) WABA is set up to message for the same Business Manager ID as the source WABA, and also has a payment method set up.

If the source WABA is on Cloud API, make sure at least one app is subscribed to webhooks for the destination WABA.

New WABA created by a Solution Partner messaging for a client

When creating a new WABA in the Business Manager, a Solution Partner must:

  • Enter an Account Name for client (WABA Name)

  • Select a payment method

  • Select Client’s Account in the Messaging for field, and

  • Enter the client’s Business Manager ID — see Find Your Business ID in Business Manager. This must be the same ID that the source WABA is connected to.

Solution Partners can then instruct their clients to accept the Messaging For request sent to their Business Manager. To guide your customers, see Create Your WhatsApp Business Account With WhatsApp Solution Partners, Approve messaging on behalf of your business. Once the request has been accepted, the destination WABA is ready for phone migration.

If the source WABA is on Cloud API, make sure at least one app is subscribed to webhooks for the destination WABA.

New WABA created by a client and shared with a Solution Partner via Embedded Signup

This type of WABA is created once a client goes through the Embedded Signup flow on the Solution Partner’s website. To guide your customers, see Create Your WhatsApp Business Account With WhatsApp Solution Partners, Embedded Signup. During the Embedded Signup flow, instruct the client to:

  • Select the same business as the one that owns their existing WABA.

  • Do not add a phone number via signup flow —we’ll be using the migration API for this. Clients can finish the Embedded Signup flow after creating their WhatsApp Business Account.

Use Embedded Signup APIs to get the WABA created by the client, add system users, and set up a payment method for the WABA.

Since the WABA is already shared with the Solution Partner, the WABA is ready for phone migration. Reminder: The migration only happens if the client’s business has completed Business Verification.

If the source WABA is on Cloud API, make sure at least one app is subscribed to webhooks for the destination WABA.


Source WABA Deletion

If you plan on deleting the source WABA after completing migration, verify that all of the templates you require have been duplicated in the destination WABA before deleting the source WABA.

Get Started

All migration calls are made to the endpoint with the destination WABA’s ID. Phone migration is always initiated by the Solution Partner or business that owns the destination WABA.

Step 1: Disable Two-Step Verification

Two-step verification must be disabled on the phone number before you can initiate migration. For Cloud API users, this can be done via the Meta Business Manager. For On-Premises API users, this can be done by making a call to the Two-Step Verification endpoint.

If you own the source WABA and the phone number owner has asked you to migrate their number, you can disable two-step verification yourself. If you do not own the source WABA, the phone number owner must ask the source WABA owner to disable two-step verification on their phone number.

Step 2: Initiate Phone Migration

Make a POST call to the /WHATSAPP_BUSINESS_ACCOUNT_ID/phone_numbers endpoint —remember that WHATSAPP_BUSINESS_ACCOUNT_ID represents the ID of the destination WABA. On the call, specify the following fields:

Name

Description

cc

Required.

Numerical country code for the phone number being registered.

phone_number

Required.

Phone number being migrated, without the country code or plus symbol (+).

migrate_phone_number

Required.

To migrate a phone number, set this to true.

To find the ID of a WhatsApp Business Account, go to Business Manager > Business Settings > Accounts > WhatsApp Business Accounts. Find the account you want to use and click on it. A panel opens, with information about the account, including the ID.

API call example:

curl -X POST \
  https://graph.facebook.com/v18.0/DESTINATION_WHATSAPP_BUSINESS_ACCOUNT_ID/phone_numbers \
  -d ‘cc=1’ \
  -d ‘phone_number=PHONE_NUMBER’ \
  -d ‘migrate_phone_number=true’ \
  -d ‘access_token=ACCESS_TOKEN’ #See Acquire an Access Token for information.

A successful API call returns:

{
  ‘id’: ‘PHONE_NUMBER_ID’
}


Step 3: Verify Phone Ownership

Now that you have requested the migration, you need to confirm it by verifying ownership of the phone number. To do that, request a registration code with a POST call to /PHONE_NUMBER_ID/request_code. Here, PHONE_NUMBER_ID represents the ID returned from Step 1.

On the call, specify the following fields:

Name

Description

code_method

Required.

Method of receiving the registration code. Supported values: SMS and VOICE.

language

Required.

Language in which you want to receive the registration code. See language codes.

A sample call looks like this:

curl -X POST \
https://graph.facebook.com/v18.0/PHONE_NUMBER_ID/request_code \
  -d ‘code_method=SMS’ \
  -d ‘language=en_US’ \
  -d ‘access_token=ACCESS_TOKEN’ #See Acquire an Access Token for information.


If your API call returns success: true, you should get your code via the selected code_method to the phone number being migrated —it may take a few minutes for the code to be delivered. The phone number’s owner needs to provide this code before you can verify the code.

To verify the code, make an API call to the /PHONE_NUMBER_ID/verify_code endpoint. Specify the following field:

Name

Description

code

Required.

6-digit registration code received after making the /PHONE_NUMBER_ID/request_code call.

For example:

curl -X POST \
https://graph.facebook.com/v18.0/PHONE_NUMBER_ID/verify_code \
  -d ‘code=6-DIGIT-CODE’ \
  -d ‘access_token=ACCESS_TOKEN’ #See Acquire an Access Token for information.

If your API call returns {“success”:true}, the ownership of your phone number is verified.

Step 4: Register Phone Number

On-Premises Numbers

Now you can download the certificate from Business Manager, or make an API call to download the certificate.

To register your phone, make an API call to the account endpoint. Since the phone number is already verified, you do not need to worry about the registration code. The verify API call is not required.

The phone number remains active with the source WABA until the phone number is registered with the API Client. To keep your account secure, enable the two-factor authentication pin after migration.

Cloud API Numbers

Send a POST request along with your 6-digit PIN to the WhatsApp Business Phone Number > Register endpoint to register the phone number again. See Register the business phone number.

Step 5 for OBAs: Re-Enable 2-Step Authentication

If you migrated the business phone number to an Official Business Account (OBA) WABA on the On-Premises API, enable two-step authentication again in order to keep your account secure and retain OBA status.

Subscribe to Webhooks to get notifications about messages your business receives and customer profile updates.

Create an Endpoint

Before you can start receiving notifications you will need to create an endpoint on your server to receive notifications.

Your endpoint must be able to process two types of HTTPS requests: Verification Requests and Event Notifications. Since both requests use HTTPs, your server must have a valid TLS or SSL certificate correctly configured and installed. Self-signed certificates are not supported.

Learn more about Verifying Requests and Event Notifications

Webhooks set up will not affect the phone number on your WhatsApp Business App. Only after you migrate your number over to the WhatsApp Business Platform can you no longer use that number on your WhatsApp Business App.

 

Subscribe to Webhooks

To subscribe to Webhooks, you will need to get a Meta App ID and permissions. To do this go to the Meta App Dashboard. There you will:

  1. Create a Business Type App in the Meta App Dashboard

  2. Add the Webhooks Product to your Meta app in the App Dashboard

  3. 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.

If you are a Solution Partner, you may need to:

  1. Add the whatsapp_business_messaging permission in your App Dashboard

  2. Successfully complete Meta App Review – This step will take time but you can continue to test during the entire review process.

 

Understanding Webhooks

Whenever a trigger event occurs, the WhatsApp Business Platform sees the event and sends a notification to a Webhook URL you have previously specified. You can get two types of notifications:

  • Received messages: This alert lets you know when you have received a message. These can also be called “inbound notifications” throughout the documentation.

  • Message status and pricing notifications: This alert lets you know when the status of a message has changed —for example, the message has been read or delivered. These can also be called “outbound notifications” throughout the documentation.

All Webhooks have the following generic format:

{
  “object”: “whatsapp_business_account”,
  “entry”: [{
      “id”: “WHATSAPP_BUSINESS_ACCOUNT_ID”,
      “changes”: [{
          “value”: {
              “messaging_product”: “whatsapp”,
              “metadata”: {
                  “display_phone_number”: “PHONE_NUMBER”,
                  “phone_number_id”: “PHONE_NUMBER_ID”
              },
              # specific Webhooks payload           
          },
          “field”: “messages”
        }]
    }]
}

See Components for information on each field.

If you receive a message that is not supported for Cloud API, you will get an unknown message webhook.

 

Payload Size

Webhooks payloads can be up to 3MB.

 

Sample App Endpoints

Create a sample app endpoint to test your webhooks.

 

Webhook Delivery Failure

If we send a webhook request to your endpoint and your server responds with an HTTP status code other than 200, or if we are unable to deliver the webhook for another reason, we will keep trying with decreasing frequency until the request succeeds, for up to 7 days.

Note that retries will be sent to all apps that have subscribed to webhooks (and their appropriate fields) for the WhatsApp Business Account. This can result in duplicate webhook notifications.

 

IP Addresses

You can get the IP addresses of our webhook servers by running the following command in your terminal:

whois -h whois.radb.net — ‘-i origin AS32934’ | grep ^route | awk ‘{print $2}’ | sort

We periodically change these IP addresses so if you are allow-listing our servers you may want to occasionally regenerate this list and update your allow-list accordingly.

 

Next Steps

Learn more about the information you can receive in a Webhooks notification.

 

The Cloud API is built on the Graph API, so if you are unfamiliar with handling Graph API error responses, see Graph API’s error handling documentation.

In general, we recommend that you build your app’s error handling logic around code values and details payload properties. These properties and their values are more indicative of the underlying error.

Code titles, which do not have a dedicated property in API error response payloads, are included as part of the message value. However, we recommend that you do not rely on titles for your error handling logic as titles will eventually be deprecated.

 

Webhooks

Some errors returned by our APIs are also reported via webhook. We are gradually rolling out webhook reporting for all API error responses over the next few months. You will receive these additional reports automatically if you are subscribed to the messages webhook field. API errors can be surfaced in the following webhook objects:

Cloud API

  • entry.changes.value.errors

  • entry.changes.value.messages.errors


On-Premises API

  • errors

 

Error Response Syntax

{
  “error”: {
    “message”: “<MESSAGE>”,
    “type”: “<TYPE>”,
    “code”: <CODE>,
    “error_data”: {
        “messaging_product”: “whatsapp”,
        “details”: “<DETAILS>”
    },
    “error_subcode”: <ERROR_SUBCODE>
    “fbtrace_id”: “<FBTRACE_ID>”
  }
}

 

Error Response Contents

Property

Value Type

Description

code

Integer

Error code. We recommend that you build your app’s error handling around error codes instead of subcodes or HTTP response status codes.

details

String

Error description and a description of the most likely reason for the error. May also contain information on how to address the error, such as which parameter is invalid or what values are acceptable.

error_subcode

Integer

Deprecated. Will not be returned in v16.0+ responses.



Graph API subcode. Not all responses will include a subcode, so we recommend that you build your error handling logic around code and details properties instead.

fbtrace_id

String

Trace ID you can include when contacting Direct Support. The ID may help us debug the error.

message

String

Combination of the error code and its title. For example: (#130429) Rate limit hit.

messaging_product

String

Messaging product. This will always be the string whatsapp for Cloud API responses.

type

String

Error type.

 

Sample Response

{
  “error”: {
    “message”: “(#130429) Rate limit hit”,
    “type”: “OAuthException”,
    “code”: 130429,
    “error_data”: {
        “messaging_product”: “whatsapp”,
        “details”: “Message failed to send because there were too many messages sent from this phone number in a short period of time”
    },
    “error_subcode”: 2494055,
    “fbtrace_id”: “Az8or2yhqkZfEZ-_4Qn_Bam”
  }
}

 

Error Codes

Authorization Errors

Code

Description

Possible Solutions

HTTP Status Code

0

AuthException

We were unable to authenticate the app user.

Typically this means the included access token has expired, been invalidated, or the app user has changed a setting to prevent all apps from accessing their data. We recommend that you get a new access token.

401

Unauthorized

3

API Method

Capability or permissions issue.

Use the access token debugger to verify that your app has been granted the permissions required by the endpoint. See Troubleshooting.

500

Internal Server Error

10

Permission Denied

Permission is either not granted or has been removed.

Use the access token debugger to verify that your app has been granted the permissions required by the endpoint. See Troubleshooting.

Ensure that the phone number used to set the business public key is allowlisted.

403

Forbidden

190

Access token has expired

Your access token has expired.

Get a new access token.

401

Unauthorized

200-299

API Permission

Permission is either not granted or has been removed.

Use the access token debugger to verify that your app has been granted the permissions required by the endpoint. See Troubleshooting.

403

Forbidden

 

Throttling Errors

Code

Description

Possible Solutions

HTTP Status Code

4

API Too Many Calls

The app has reached its API call rate limit.

Load the app in the App Dashboard and view the Application Rate Limit section to verify that the app has reached its rate limit. If it has, try again later or reduce the frequency or amount of API queries the app is making.

429

Too many requests

80007

Rate limit issues

The WhatsApp Business Account has reached its rate limit.

See WhatsApp Business Account Rate Limits. Try again later or reduce the frequency or amount of API queries the app is making.

429

Too many requests

130429

Rate limit hit

Cloud API message throughput has been reached.

The app has reached the API’s throughput limit. See Throughput. Try again later or reduce the frequency with which the app sends messages.

400

Too many requests

131048

Spam rate limit hit

Message failed to send because there are restrictions on how many messages can be sent from this phone number. This may be because too many previous messages were blocked or flagged as spam.

Check your quality status in the WhatsApp Manager and see the Quality-Based Rate Limits documentation for more information.

429

Too many requests

131056

(Business Account, Consumer Account) pair rate limit hit

Too many messages sent from the sender phone number to the same recipient phone number in a short period of time.

Wait and retry the operation, if you intend to send messages to the same phone number. You can still send messages to a different phone number without waiting

400

Too many requests

 

Integrity Errors

Code

Description

Possible Solutions

HTTP Status Code

368

Temporarily blocked for policies violations

The WhatsApp Business Account associated with the app has been restricted or disabled for violating a platform policy.

See the Policy Enforcement document to learn about policy violations and how to resolve them.

403

Forbidden

131031

Account has been locked

The WhatsApp Business Account associated with the app has been restricted or disabled for violating a platform policy, or we were unable to verify data included in the request against data set on the WhatsApp Business Account (e.g, the two-step pin included in the request is incorrect).

See the Policy Enforcement document to learn about policy violations and how to resolve them.

403

Forbidden

 

Other Errors

Code

Description

Possible Solutions

HTTP Status Code

1

API Unknown

Invalid request or possible server error.

Check the WhatsApp Business Platform Status page to see API status information. If there are no server outages, check the endpoint reference and verify that your request is formatted correctly and meets all endpoint requirements.

400

Bad Request

2

API Service

Temporary due to downtime or due to being overloaded.

Check the WhatsApp Business Platform Status page to see API status information before trying again.

503

Service Unavailable

33

Parameter value is not valid

The business phone number has been deleted.

Verify that the business phone number is correct.

400

Bad Request

100

Invalid parameter

The request included one or more unsupported or misspelled parameters.

See the endpoint’s reference to determine which parameters are supported and how they are spelled.

Ensure when setting the business public key, it is a valid 2048-bit RSA public key in PEM format.

Ensure there is no mismatch between the phone number id you are registering and a previously stored phone number id.

400

Bad Request

130472

User’s number is part of an experiment

Message was not sent as part of an experiment.

See Marketing Message Experiment.

400

Bad Request

131000

Something went wrong

Message failed to send due to an unknown error.

When setting a business public key, it either failed to calculate the signature, call the GraphQL endpoint, or the GraphQL endpoint returned an error.

Try again. If the error persists, open a Direct Support ticket.

500

Internal Server Error

131005

Access denied

Permission is either not granted or has been removed.

Use the access token debugger to verify that your app has been granted the permissions required by the endpoint. See Troubleshooting.

403

Forbidden

131008

Required parameter is missing

The request is missing a required parameter.

See the endpoint’s reference to determine which parameters are required.

400

Bad Request

131009

Parameter value is not valid

One or more parameter values are invalid.

See the endpoint’s reference to determine which values are supported for each parameter, and see Phone Numbers to learn how to add a phone number to a WhatsApp Business Account.

400

Bad Request

131016

Service unavailable

A service is temporarily unavailable.

Check the WhatsApp Business Platform Status page to see API status information before trying again.

500

Internal Server Error

131021

Recipient cannot be sender

Sender and recipient phone number is the same.

Send a message to a phone number different from the sender.

400

Bad Request

131026

Message Undeliverable

Unable to deliver message. Reasons can include:



  • The recipient phone number is not a WhatsApp phone number.

  • Recipient has not accepted our new Terms of Service and Privacy Policy.

  • Recipient using an old WhatsApp version; must use the following WhatsApp version or greater:

  • Android: 2.21.15.15

  • SMBA: 2.21.15.15

  • iOS: 2.21.170.4

  • SMBI: 2.21.170.4

  • KaiOS: 2.2130.10

  • Web: 2.2132.6

Confirm with the recipient that they agree to be contacted by you over WhatsApp and are using the latest version of WhatsApp.

400

Bad Request

131042

Business eligibility payment issue

Message failed to send because there were one or more errors related to your payment method.

See About Billing For Your WhatsApp Business Account and verify that you have set up billing correctly.



Common problems:



  • Payment account is not attached to a WhatsApp Business Account

  • Credit line is over the limit

  • Credit line (Payment Account) not set or active

  • WhatsApp Business Account is deleted

  • WhatsApp Business Account is suspended

  • Timezone not set

  • Currency not set

  • MessagingFor request (On Behalf Of) is pending or declined

  • Exceeded conversation free tier threshold without a valid payment method

400

Bad Request

131045

Incorrect certificate

Message failed to send due to a phone number registration error.

Register the phone number before trying again.

500

Internal Server Error

131047

Re-engagement message

More than 24 hours have passed since the recipient last replied to the sender number.

Send the recipient a business-initiated message using a message template instead.

400

Bad Request

131051

Unsupported message type

Unsupported message type.

See Messages for supported message types before trying again with a supported message type.

400

Bad Request

131052

Media download error

Unable to download the media sent by the user.

We were unable to download the media for one or more reasons, such as an unsupported media type. Refer to the error.error_data.details value for more information about why we were unable to download the media.

400

Bad Request

131053

Media upload error

Unable to upload the media used in the message.

We were unable to upload the media for one or more reasons, such as an unsupported media type. Refer to the error.error_data.details value for more information about why we were unable to upload the media.



For more reliable performance when sending media, refer to Media HTTP Caching and uploading the media.

400

Bad Request

132000

Template Param Count Mismatch

The number of variable parameter values included in the request did not match the number of variable parameters defined in the template.

See Message Template Guidelines and make sure the request includes all of the variable parameter values that have been defined in the template.

400

Bad Request

132001

Template does not exist

The template does not exist in the specified language or the template has not been approved.

Make sure your template has been approved and the template name and language locale are correct. Please ensure you follow message template guidelines.

404

Not Found

132005

Template Hydrated Text Too Long

Translated text is too long.

Check the WhatsApp Manager to verify that your template has been translated. See Quality Rating and Template Status.

400

Bad Request

132007

Template Format Character Policy Violated

Template content violates a WhatsApp policy.

See Rejection Reasons to determine possible reasons for violation.

400

Bad Request

132012

Template Parameter Format Mismatch

Variable parameter values formatted incorrectly.

The variable parameter values included in the request are not using the format specified in the template. See Message Template Guidelines.

400

Bad Request

132015

Template is Paused

Template is paused due to low quality so it cannot be sent in a template message.

Edit the template to improve its quality and try again once it is approved.

400

Bad Request

132016

Template is Disabled

Template has been paused too many times due to low quality and is now permanently disabled.

Create a new template with different content.

400

Bad Request

132068

Flow is blocked

Flow is in blocked state.

Correct the Flow

400

Bad Request

132069

Flow is throttled

Flow is in throttled state and 10 messages using this flow were already sent in the last hour.

Correct the Flow

400

Bad Request

133000

Incomplete Deregistration

A previous deregistration attempt failed.

Deregister the number again before registering.

500

Internal Server Error

133004

Server Temporarily Unavailable

Server is temporarily unavailable.

Check the WhatsApp Business Platform Status page to see API status information and check the response details value before trying again.

503

Service Unavailable

133005

Two step verification PIN Mismatch

Two-step verification PIN incorrect.

Verify that the two-step verification PIN included in the request is correct.



To reset the two-step verification PIN:



  1. Disable two-step verification.

  2. Send a POST request that includes the new PIN to the Phone Number endpoint.

400

Bad Request

133006

Phone number re-verification needed

Phone number needs to be verified before registering.

Verify the phone number before registering it.

400

Bad Request

133008

Too Many two step verification PIN Guesses

Too many two-step verification PIN guesses for this phone number.

Try again after the amount of time specified in the details response value.

400

Bad Request

133009

Two step verification PIN Guessed Too Fast

Two-step verification PIN was entered too quickly.

Check the details response value before trying again.

400

Bad Request

133010

Phone number Not Registered

Phone number not registered on the Whatsapp Business Platform.

Register the phone number before trying again.

400

Bad Request

133015

Please wait a few minutes before attempting to register this phone number

The phone number you are attempting to register was recently deleted, and deletion has not yet completed.

Wait 5 minutes before re-trying the request.

400

Bad Request

135000

Generic user error

Message failed to send because of an unknown error with your request parameters.

See the endpoint’s reference to determine if you are querying the endpoint using the correct syntax. Contact customer support if you continue receiving this error code in response.

400

Bad Request



 

Documents