# Migrating from Cloud API to On-Premises 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](https://developers.facebook.com/docs/whatsapp/business-management-api/guides/migrate-phone-to-different-waba/).

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](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/migrating-from-cloud-to-onprem#api-differences) and take appropriate action to address them before performing the migration steps described in this document.

### Best Practices <a href="#best-practices" id="best-practices"></a>

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 <a href="#api-differences" id="api-differences"></a>

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

#### Webhooks <a href="#webhooks" id="webhooks"></a>

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:

* Configuration: [Webhooks for WhatsApp](https://developers.facebook.com/docs/graph-api/webhooks/getting-started/webhooks-for-whatsapp)
* Cloud API webhook payloads: [Webhooks Notification Payload Reference](https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/components)
* Business Management API webhook payloads: [Webhooks Setup](https://developers.facebook.com/docs/whatsapp/business-management-api/guides/set-up-webhooks)

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 <a href="#media" id="media"></a>

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](https://developers.facebook.com/docs/whatsapp/on-premises/reference/media) to generate new media IDs, or use media URLs if the media is hosted on a public server. See [Sending Media Messages](https://developers.facebook.com/docs/whatsapp/api/messages/media).

#### Error Codes <a href="#error-codes" id="error-codes"></a>

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

* [Cloud API Error Codes](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes)
* [Business Management API Error Codes](https://developers.facebook.com/docs/whatsapp/business-management-api/error-codes)

#### Push-To-Talk Messages <a href="#push-to-talk-messages" id="push-to-talk-messages"></a>

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 <a href="#downtime" id="downtime"></a>

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 <a href="#step-1--integrate-on-premises-api" id="step-1--integrate-on-premises-api"></a>

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 <a href="#step-2--prepare-for-migration" id="step-2--prepare-for-migration"></a>

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](https://developers.facebook.com/docs/whatsapp/guides/network-requirements).

### Step 3: Register API Client <a href="#step-3--register-api-client" id="step-3--register-api-client"></a>

Register the business phone number on your On-Premises API client. To do that, call the [`/account` endpoint](https://developers.facebook.com/docs/whatsapp/api/account):

```
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](https://developers.facebook.com/docs/whatsapp/api/account/verify) to complete registration.

See all available fields for this endpoint [here](https://developers.facebook.com/docs/whatsapp/api/account#parameters).

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

### Step 4: Set Shards <a href="#step-4--set-shards" id="step-4--set-shards"></a>

Once your client is registered, you can [set shards](https://developers.facebook.com/docs/whatsapp/multiconnect_mc), if needed.

### Step 5: Start Sending Messages <a href="#step-5--start-sending-messages" id="step-5--start-sending-messages"></a>

You are ready to send messages to your customers. See the [Send Messages](https://developers.facebook.com/docs/whatsapp/guides/messages) guides for guidance.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.is-messenger.com/ismessenger/messaging-channels/whatsapp/whatsapp-cloud-api/migrating-from-cloud-api-to-on-premises-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.