Migrating from Cloud API to On-Premises API

This document explains how to migrate business phone numbers from Cloud API to On-Premises API. To migrate from On-Premises API to Cloud API, see Migrating from On-Premises API to Cloud API.

Note that migrating a business phone number from one API to another is not the same as migrating a number from one WhatsApp Business Account (WABA) to another.

Migration does NOT affect:

  • the business phone number's display name, verification status, or quality rating

  • templates used by the business phone number, or their statuses

  • the owning WABA, its Official Business Account status, or its messaging limit

In order to support migration, however, you must be aware of any API differences and take appropriate action to address them before performing the migration steps described in this document.

Best Practices

After making sure that your app can handle all API differences, we recommend that you first migrate a low-volume business phone number and verify that all functionality that you intend to offer with On-Premises API works correctly. After verifying that everything is working properly, migrate additional numbers.

We also recommend that you perform migration when traffic to your On-Premises API deployment is low.

API Differences

Make sure your app is able to handle these differences before starting the migration process.

Webhooks

Cloud API and Business Management API webhooks payload structures are different from On-Premises API payload structures. We recommend that you create a new webhook endpoint that can handle On-Premises API webhooks exclusively.

Refer to the following documents to help you understand payload differences:

Once migration to On-Premises API is complete, the business phone number's Cloud API webhooks will no longer be delivered and On-Premises API webhooks delivery will begin.

Media

Media IDs for any media uploaded to Cloud API cannot be used when sending messages with On-Premises API, so you must either reupload media using On-Premises API to generate new media IDs, or use media URLs if the media is hosted on a public server. See Sending Media Messages.

Error Codes

Cloud API and Business Management API error codes are different from On-Premises API error codes. See the following documents:

Push-To-Talk Messages

On-Premises identifies push-to-talk (PTT) messages in webhooks by setting messages.type to voice, but Cloud API identifies PTT messages by setting messages.audio.voice to true.

Downtime

Downtime begins as soon as you perform registration step (step 3) and should only last a few seconds. During this time, messages sent to the number from WhatsApp users will be silently dropped.

We highly encourage you to schedule migration during a time when the number experiences low activity, to minimize any downtime impact.

Step 1: Integrate On-Premises API

Since you are migrating a business phone number to On-Premises API, make sure that your app can successfully use your On-Premises API client and that the WhatsApp Business Account associated with the business phone number has webhooks configured correctly.

Step 2: 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 3: Register API Client

Register the business phone number on your On-Premises 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 4: Set Shards

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

Step 5: Start Sending Messages

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

PreviousMigrating from On-Premises API to Cloud APINextSet up the WhatsApp Echo Bot

Last updated