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:

• Register as a Meta Developer

• Enable two-factor authentication for your account

• Create a Meta App: Go to developers.facebook.com > My Apps > Create App. Select the Business type and follow the prompts on your screen. If you are asked to choose a Use Case as part of the app creation flow, choose Other as your use case, then select Business.

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:

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

6. Generate a WhatsApp Business Account.

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

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

    

2. Send a Test Message

In the WhatsApp > API Setup panel:

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

    

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

     

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

12. 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” } } }’

     

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

   

  • A Meta business account.

  • A WhatsApp Business Account, associated with your Meta business account.

  • A business app, associated with your Meta business account.

  • Either a System User access token or a User access token.

  • The whatsapp_business_management permission

  • If your app needs to access endpoints that target your business account, you will also need the business_management permission

     

  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.

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

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.

Once you have completed the app creation flow your app will be loaded 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:

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:

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

Before You Start

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

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:

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:

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:

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:

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:

4. Add the whatsapp_business_messaging permission in your App Dashboard

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

• Sample App Endpoints using Glitch

• Sample App Endpoints using Heroku
  
  

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

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

Throttling Errors

Integrity Errors

Other Errors