WhatsApp Business Cloud API

Migrate Between On-Premises and Cloud API

This guide walks you through the process of migrating between On-Premises and Cloud API.

From On-Premises to Cloud

To use the Cloud API as a Business Solution Provider (BSP), you need to have advanced access to the business_management, whatsapp_business_management, and whatsapp_business_messaging permissions. If you are a direct developer, you can skip App Review and move on to "Step 0".

If you are working as a Business Solution Provider (BSP), you likely already have advanced access to the business_management and whatsapp_business_management permissions. Now, to use the Cloud API, you need to submit your existing Meta app for App Review. During the review process, you need to request additional access to the whatsapp_business_messaging permission.

Step 0: Write a new Connector for Cloud API

The API endpoints and signatures for the Cloud API are different from the On-premises API, so you need to write a new integration for Cloud API.

Step 1: Select Best Time for Migration

We recommend performing migration during a maintenance window while traffic to the On-Premises deployment is low/turned off. Downtime is typically less than 5 minutes, and no re-verification of the phone number is required.

Step 2: Backup On-Premises Content

We don’t provide full database migration, so you must back up your data before moving a phone number from On-Premises to Cloud API. Before starting the backup, make sure you are in single instance mode and not multi-connect.

Once you are ready, use the On-Premises Backup API:

POST /v1/settings/backup
{
    "password": "PASSWORD"
}

A successful response looks like this:

{
    "settings": {
       "data": "ENCRYPTED_BACKUP_DATA"
    }
}

Save the data for the next step.

Step 3: Call /register on Cloud API to Start Migration

To migrate your account, make a POST call to the PHONE_NUMBER_ID/register endpoint. Inside the backup object, include the backup data obtained during the previous step:

curl -X POST \ 
    'https://graph.facebook.com/v13.0/FROM_PHONE_NUMBER_ID/register' \
    -H 'Authorization: Bearer SYSTEM_USER_ACCESS_TOKEN' \
    -d '{
    "messaging_product": "whatsapp",
    "pin": "6_DIGIT_PIN",
    “backup”: {
    "password": "PASSWORD",
    "data": "BACKUP_DATA"
    }
    }'

A successful response looks like this:

{
  "success": true
}

See all available fields for this endpoint here.

Step 4: Prepare to Send Messages

You have been migrated to the Cloud API. But, before sending messages, you should perform necessary operations, like re-uploading media files you want to send. Be aware that data (messages, media, etc.) received on the On-Premises API deployment before migration won’t be available in the Cloud API after migration.

Step 5: Start Sending Messages

You are ready to send messages to your customers. See the /messages endpoint documentation for guidance.

From Cloud to On-Premises

To migrate from Cloud API to On-Premises API, follow these steps:

Step 0: Make Sure you Have a Connector for On-Premises API

The API endpoints and signatures for the On-premises API are different from the Cloud API, so you need to write a new integration for On-premises API, or make sure you use your existing On-premises connector.

Step 1: Prepare for Migration

We suggest that you stop sending messages while you complete the migration.

The WhatsApp Business API On-Premises client has certain network requirements for connecting to the WhatsApp servers. To make sure you are ready, check Set Up and Debug Your Network.

Step 2: Register API Client

To move from Cloud API to On-Premises you need to register your WhatsApp Business API client. To do that, call the /account endpoint:

POST /v1/account

{
    "cc": "COUNTRY_CODE",
    "phone_number": "PHONE_NUMBER_WITHOUT_COUNTRY_CODE",
    "method": "sms" or "voice",
    "cert": "VERIFIED_NAME_CERT_IN_BASE64",
    "pin": "EXISTING_6_DIGIT_PIN" # required if two-step verification is enabled
}

Depending on the response received, the registration procedure can be considered complete or require another step to complete. If successful, you receive one of the following HTTP status codes. Follow the instructions that match the response you received:

  • 201 Created — The account already exists. You are already registered, so you do not need to do anything else.
  • 202 Accepted — The account does not exist. Depending on the method selected in the request, check your SMS or voice number for the registration code. This response will include a returned payload that contains the vname decoded from the cert parameter for you to confirm the right display name is being set. If correct, proceed to Completing Your Account Registration to complete registration.

See all available fields for this endpoint here.

Once the registration is complete, the On-Premises API client will be the one receiving messages.

Step 3: Set Shards

Once your client is registered, you can set shards, if needed.

Step 4: Start Sending Messages

You are ready to send messages to your customers. See the Send Messages guides for guidance.