Guide to migrating from On-Premise to Cloud API

Meta has officially announced that it will gradually stop supporting the On-Premise WhatsApp Business API in 2025. This means accounts currently running in an On-Premise environment will no longer receive feature updates, security maintenance, or official technical support. To ensure your business is not disrupted and you can continue using the latest WhatsApp features, you need to migrate your existing phone numbers to WhatsApp Cloud API.

If you previously used WhatsApp Business via an On-Premise API on another platform, this document provides a complete procedure to help you successfully complete the migration.

Migrate existing WhatsApp phone numbers

Applicable to:

Those currently managing WhatsApp Business numbers through another platform (BSP / On-Premise API) who want to move to this platform and use the Cloud API.

Method A: Unlink from the existing On-Premise and switch to Cloud API

1. Important Notes

  1. Number ownership: The phone number belongs to your WhatsApp Business Account (WABA), not to any BSP.

  2. Historical messages: After migration, past message histories will not be automatically transferred. If you need to retain them, please back them up before migrating.

  3. Downtime: During the migration process, the number will be temporarily unable to send or receive messages, typically lasting from a few minutes to several tens of minutes.

  4. Irreversible: Once a number is bound to the Cloud API, it cannot be reverted to the On-Premise API.

2. Pre-migration preparation

  • Confirm you have Meta Business Manager administrator permissions.

  • Confirm the number can receive OTPs (SMS or voice call).

  • Notify relevant teams of the migration time to avoid impacting business operations.

3. Migration process

Step 1. Release the number (operate on the old platform)

  1. Log in to the BSP or On-Premise API platform you are currently using.

  2. Find the phone number settings, and unlink / deactivate the API connection.

  3. Confirm the number has been released and is no longer shown as occupied.

Step 2. Bind following the integration article

  1. Attempt again to integrate via WhatsApp WhatsApp (Cloud API) method.

Method B: Delete and recreate the number

In some cases, if you cannot use the official number migration (Number Migration) process, you can still choose to delete and recreate.

the existing WhatsApp Business API number.

  • However, using this method will have the following impacts: All existing assets will be lost, includingdisplay name (Display Name),display name (Display Name)approved message templates (Message Templates) quality rating (Quality Rating) and.

  • messaging limits (Messaging Limits) DowntimeDuring the deletion and re-registration process, the number will have an unavoidable

period during which it cannot send or receive messages.

  1. Operational steps

    • Log in to Meta Business Manager

    • Go to Meta Business Manager.

  2. Log in with an account that has admin permissions.

    • Enter WhatsApp account management In the left menu find.

    • Business Settings Click.

  3. Accounts > WhatsApp Accounts (WhatsApp Accounts)

    • Select the target number

    • Business Settings Find the WhatsApp Business number you want to delete..

  4. Phone Numbers

    • Delete the number In that number's settings, choose.

    • Remove / Delete

  5. The system will prompt for confirmation; after completion the number will be removed from the WABA.

Recreate and bind to Cloud API

How to disable two-step verification (2FA) for a WhatsApp Business phone number If your number is connected through a WhatsApp Business Solution Provider (BSP)

  1. you need to contact that provider to help disable 2FA for the number. You will not be able to perform the following yourself. Log in to your.

  2. WhatsApp Business Manager as described above In the left panel, go to.

  3. Account Tools > Phone Numbers On the number for which you want to disable 2FA, click.

  4. Settings Go toTwo-step Verification and then select.

Turn off two-step verification If you do not see these options, you need to contact your current service provider and ask them to disable 2FA for your WhatsApp number. For more information, refer to the official Facebook documentation.

https://developers.facebook.com/docs/whatsapp/on-premises/reference/settings/two-step-verification#disable

  1. Frequently Asked Questions (FAQ)

    • Messages disappeared after migration?

  2. This is normal; the Cloud API will not bring in old messages.

    • Not receiving OTP codes?

    • Please confirm the number can properly send and receive SMS or voice calls.

  3. It is recommended to try again during off-peak hours.

    • Can I go back to On-Premise?

  4. No. Once the number has been moved to the Cloud API, it cannot be reverted.

    • Will charges change?

PreviousTroubleshootingNextWhatsApp (Twilio)

Last updated