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

To migrate from Cloud API to On-Premises API, see [Migrating from Cloud API to On-Premises API](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/migrating-from-cloud-to-onprem).

### How It Works <a href="#how-it-works" id="how-it-works"></a>

The migration process involves generating metadata about the business phone number, then using that data to register the number for use with Cloud API. This in turn deregisters the number from On-Premises API, since a number can only be registered for use with one API at a time.

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-onprem-to-cloud#api-differences) and take appropriate action to address them before performing the migration steps described in this document.

### Requirements <a href="#requirements" id="requirements"></a>

#### Meta App <a href="#meta-app" id="meta-app"></a>

You must have a Meta business app that is able to use Cloud API and Business Management API with onboarded customer data, and that is able to digest Cloud API and Business Management API [webhooks](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/migrating-from-onprem-to-cloud#webhooks). The app must also be associated with, or claimed by, your verified Meta Business Account.

If you do not have a Meta business app, or if you have one but have not configured the WhatsApp product on it, complete the steps in our Cloud API [Get Started](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started) guide. Completing these steps will generate all of the assets needed to test Cloud API and Business Management API.

#### App Review <a href="#app-review" id="app-review"></a>

Your Meta app must undergo [App Review](https://developers.facebook.com/docs/whatsapp/embedded-signup/app-review) and be approved (i.e. have advanced access) for the **whatsapp\_business\_messaging** and **whatsapp\_business\_management** permissions.

### 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 Cloud 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>

The following On-Premises API features are either unsupported or are treated differently by Cloud API. 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 Cloud API and Business Management API exclusively.

Refer to the following documents to help you understand payload differences and how to configure webhooks on your app using the App Dashboard:

* 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)

Note that after you migrate a business phone number to Cloud API, you must use the [WhatsApp Business Account > Subscribed Apps](https://developers.facebook.com/docs/graph-api/reference/whats-app-business-account/subscribed_apps) endpoint to **subscribe your Meta app to webhooks on the WABA** associated with the business number:

**Request Syntax**

```
curl -X POST 'https://graph.facebook.com/v17.0/<WABA_ID>/subscribed_apps' \
-H 'Authorization: Bearer EAAJB...'
```

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

#### Media <a href="#media" id="media"></a>

Media IDs for any media uploaded to On-Premises API cannot be used when sending messages with Cloud API, so you must either [reupload media using Cloud API](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media#upload-media) to generate new media IDs, or use media URLs if the media is hosted on a public server. See [Media Messages](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-messages#media-messages) and [Media-Based Message Templates](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-message-templates#media-based).

Note that to ensure message integrity, some media hosting domains that are allowed by On-Premises API are not allowed by Cloud API. If you use a hosting service for your media, we recommend that you test media URLs in free-form messages and template messages prior to migration. If you believe your host is blocked in error, please [contact support](https://developers.facebook.com/docs/whatsapp/support).

#### 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)

#### Property Validation <a href="#property-validation" id="property-validation"></a>

* On-Premises API can accept unknown properties in message post body payloads, but Cloud API will reject these requests, so make your message send requests use only supported properties.
* On-Premises API allows the omission of button indexes when sending messages with only one button, but Cloud API will reject these requests, so make sure your message send requests that include buttons also include indexes and their values.
* On-Premises API accepts text strings that contain leading or trailing spaces (or only spaces) on action and button object properties when sending interactive messages, but Cloud API will reject these requests.

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

#### Stickerpacks <a href="#stickerpacks" id="stickerpacks"></a>

Cloud API does not support stickerpacks.

### Downtime <a href="#downtime" id="downtime"></a>

Downtime begins as soon as you perform the final migration step (registering the number for use with Cloud API) 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.

### Throughput <a href="#throughput" id="throughput"></a>

If the On-Premises business phone number has multi-connect running 2 or more shards, it will automatically be upgraded to [high throughput](https://developers.facebook.com/docs/whatsapp/cloud-api/overview#throughput) on Cloud API.

### Migration Support <a href="#migration-support" id="migration-support"></a>

If you have questions or need help with migration, submit a Direct Support ticket with:

* Topic: **WABiz: Cloud API**
* Request Type: **On-Premises API -> Cloud API Migration Issues**

### Step 1: Disable Two-Step Verification <a href="#step-1--disable-two-step-verification" id="step-1--disable-two-step-verification"></a>

If you know the business phone number's PIN, you can skip this step.

You will need the business phone number's PIN when performing step 3, so if you do not know the PIN, you must first [disable two-step verification](https://developers.facebook.com/docs/whatsapp/on-premises/reference/settings/two-step-verification#disable) on the business phone number. If you do not own the business phone number, ask the owner to disable it for you.

### Step 2: Generate Phone Number Metadata <a href="#step-2--generate-phone-number-metadata" id="step-2--generate-phone-number-metadata"></a>

Use the [Backup and Restore API](https://developers.facebook.com/docs/whatsapp/on-premises/reference/settings/backup-and-restore) to generate metadata about your business phone number.

#### Request Syntax <a href="#request-syntax" id="request-syntax"></a>

```
POST /v1/settings/backup
{
  "password": "<PASSWORD>"
}
```

The `<PASSWORD>` can be any string. This value will be used to encode the metadata, so keep track of it as you will need it in the next step.

#### Response <a href="#response" id="response"></a>

```
{
  "settings": {
    "data": "<METADATA>"
  },
  "meta": {
    "api_status": "<API_STATUS>",
    "version": "<API_VERSION>"
  }
}
```

The API will return an encoded string assigned to the `data` property that describes your business phone number and its settings. Capture this value as you will need it in the next step.

* `<METADATA>` — This is the encoded string that describes your business phone number and its settings. Capture this value as you will need it in the next step.
* `<API_STATUS>` — The status of your On-Premises API deployment.
* `<API_VERSION>` —The On-Premises API version number that you are running.

#### Example Request <a href="#example-request" id="example-request"></a>

```
curl 'https://localhost:9090/v1/settings/backup' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "password": "tacocat"
}'
```

#### Example Response <a href="#example-response" id="example-response"></a>

```
{
  "settings": {
    "data": "V0FCS..."
  },
  "meta": {
    "api_status": "stable",
    "version": "2.49.3"
  }
}
```

### Step 3: Register the Number <a href="#step-3--register-the-number" id="step-3--register-the-number"></a>

Use the Cloud API [WhatsApp Business Phone Number > Register](https://developers.facebook.com/docs/graph-api/reference/whats-app-business-account-to-number-current-status/register/) endpoint to register the number for use with Cloud API. Include the encoded business phone number metadata value and the password from the previous step.

#### Request Syntax <a href="#request-syntax-2" id="request-syntax-2"></a>

```
POST /<BUSINESS_PHONE_NUMBER_ID>/register
```

#### Post Body <a href="#post-body" id="post-body"></a>

```
{
  "messaging_product": "whatsapp",
  "pin": "<NEW_OR_EXISTING_PIN>",
  "backup": {
    "password": "<PASSWORD>",
    "data": "<METADATA>"
  }
}
```

* `<NEW_OR_EXISTING_PIN`> — The existing PIN or the PIN you want to set on the business phone number.
* `<PASSWORD`> — The password you used to generate your business phone number's metadata in the previous step.
* `<METADATA`> — The encoded string that describes your business phone number and its settings, generated in the previous step.

#### Response <a href="#response-2" id="response-2"></a>

```
{
  "success": <SUCCESS>
}
```

The API will respond with `success` set to `true` if registration is successful, or `false` if there was an error.

#### Example Request <a href="#example-request-2" id="example-request-2"></a>

```
curl 'https://graph.facebook.com/v18.0/110200345501442/register' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "pin": "134568",
  "backup": {
    "password": "tacocat",
    "data": "V0FCS..."
  }
}'
```

#### Example Response <a href="#example-response-2" id="example-response-2"></a>

```
{
  "success": true
```


---

# 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-on-premises-api-to-cloud-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.