Migrating Phone Numbers Between WhatsApp Business Accounts Programmatically

This document describes how to migrate business phone numbers from one WhatsApp Business Account (WABA) to another using the API entirely. Only use this method if you are going to be working with your customer using the On-Behalf-Of model (i.e. you will create and own the destination WABA and its assets and share them with the customer).

If you would like to migrate customer phone numbers via Embedded Signup (which is recommended), see our Migrating Phone Numbers Between WhatsApp Business Accounts via Embedded Signup document.

Overview

Solution Partners and businesses directly integrated with the WhatsApp Business Platform can migrate a registered phone number from one WABA to another. Migrated phone numbers keep their display name, quality rating and messaging limit, Official Business Account status, and any High quality message templates previously approved.

In practice, migration means that a business can keep the same phone number if:

• They are using the platform with one of our Solution Partners and want to switch to a different provider.
• They are using their own implementation and want to switch to a Solution Partner.

Only Solution Partners and businesses directly integrated with the WhatsApp Business Platform can perform the phone number migration.

The migration process involves 3 main assets:

Phone migration is always initiated by the Solution Partner or business that owns the destination WABA.

WABAs are accounts created inside a business on Business Manager. Each business has an ID — that ID is also commonly known as Business Manager ID.

Both source and destination WABAs can be associated with businesses in two different ways:

How Migration Works

Downtime

Message Templates

All high quality message templates in the source WABA will be duplicated and automatically approved in the destination WABA as long as the destination WABA can accommodate new templates. Existing message templates in the destination WABA will not be affected. Low quality, rejected, or pending templates will not be duplicated.

The duplicated templates will be subjected to Template Categorization Guidelines checks to ensure that the templates are correctly categorized. This may result in some of the duplicated templates being REJECTED.

If the destination WABA cannot accommodate all of the new templates, we will duplicate as many as we can until the destination WABA'S template limit has been reached. Unduplicated templates must be re-created and submitted for approval if they are to be used by the destination WABA.

Please note that the quality ratings of templates will NOT be migrated. All migrated templates will start with an UNKNOWN rating. This rating will remain for the first 24 hours, after which a new rating will be generated if sufficient data is available.

Billing Migration

Rate Limits

Standard Graph API rate limits apply to the migration.

Limitations

• Test business phone numbers issued by WhatsApp cannot be migrated.
• Business phone numbers in use with the WhatsApp Business App cannot be migrated using this process. To migrate a number from the WhatsApp Business app, see Migrating an Existing Number for On-Premises API and Migrating an Existing Number for Cloud API.
• Message and chat history are not migrated with this process.
• The API does not support bulk migration; business phone numbers must be migrated individually.
• Business phone numbers must have an approved display name (name_status is APPROVED).
• Business phone numbers cannot have any associated pending display name change requests.
• Quality ratings of the templates will NOT be migrated. All new migrated templates will start with an APPROVED rating, and the new rating of the migrated templates will be established using the past 24h data.

Summary

Before You Start

To be eligible for migration, a business’ assets must meet the following criteria:

Permissions

All API calls for phone migration must be made with an application that has whatsapp_business_management permission. See Using The WhatsApp Business Management API section to learn more about App Review, Access Tokens, and making API calls. Phone migration is always initiated by the Solution Partner or business that owns the destination WABA.

Preparing the Destination WABA

The type of destination WABA determines what needs to be done for the account to be ready for migration:

Source WABA Deletion

If you plan on deleting the source WABA after completing migration, verify that all of the templates you require have been duplicated in the destination WABA before deleting the source WABA.

Get Started

All migration calls are made to the endpoint with the destination WABA's ID. Phone migration is always initiated by the Solution Partner or business that owns the destination WABA.

Step 1: Disable Two-Step Verification

Two-step verification must be disabled on the phone number before you can initiate migration. For Cloud API users, this can be done via the Meta Business Manager. For On-Premises API users, this can be done by making a call to the Two-Step Verification endpoint.

If you own the source WABA and the phone number owner has asked you to migrate their number, you can disable two-step verification yourself. If you do not own the source WABA, the phone number owner must ask the source WABA owner to disable two-step verification on their phone number.

Step 2: Initiate Phone Migration

Make a POST call to the /WHATSAPP_BUSINESS_ACCOUNT_ID/phone_numbers endpoint —remember that WHATSAPP_BUSINESS_ACCOUNT_ID represents the ID of the destination WABA. On the call, specify the following fields:

API call example:

curl -X POST \
  'https://graph.facebook.com/v21.0/DESTINATION_WHATSAPP_BUSINESS_ACCOUNT_ID/phone_numbers' \
  -d 'cc=1' \
  -d 'phone_number=PHONE_NUMBER' \
  -d 'migrate_phone_number=true' \
  -d 'access_token=ACCESS_TOKEN' #See Acquire an Access Token for information.

A successful API call returns:

{
  'id': 'PHONE_NUMBER_ID'
}

Step 3: Verify Phone Ownership

Now that you have requested the migration, you need to confirm it by verifying ownership of the phone number. To do that, request a registration code with a POST call to /PHONE_NUMBER_ID/request_code. Here, PHONE_NUMBER_ID represents the ID returned from Step 1.

On the call, specify the following fields:

A sample call looks like this:

curl -X POST \ 
'https://graph.facebook.com/v21.0/PHONE_NUMBER_ID/request_code' \
  -d 'code_method=SMS' \
  -d 'language=en_US' \
  -d 'access_token=ACCESS_TOKEN' #See Acquire an Access Token for information.

If your API call returns success: true, you should get your code via the selected code_method to the phone number being migrated —it may take a few minutes for the code to be delivered. The phone number's owner needs to provide this code before you can verify the code.

To verify the code, make an API call to the /PHONE_NUMBER_ID/verify_code endpoint. Specify the following field:

For example:

curl -X POST \ 
'https://graph.facebook.com/v21.0/PHONE_NUMBER_ID/verify_code' \
  -d 'code=6-DIGIT-CODE' \
  -d 'access_token=ACCESS_TOKEN' #See Acquire an Access Token for information.

If your API call returns {"success":true}, the ownership of your phone number is verified.

Step 4: Register Phone Number

On-Premises Numbers

Now you can download the certificate from Business Manager, or make an API call to download the certificate.

To register your phone, make an API call to the account endpoint. Since the phone number is already verified, you do not need to worry about the registration code. The verify API call is not required.

The phone number remains active with the source WABA until the phone number is registered with the API Client. To keep your account secure, enable the two-factor authentication pin after migration.

Cloud API Numbers

Send a POST request along with your 6-digit PIN to the WhatsApp Business Phone Number > Register endpoint to register the phone number again. See Register the business phone number.

Step 5 for OBAs: Re-Enable 2-Step Authentication

If you migrated the business phone number to an Official Business Account (OBA) WABA on the On-Premises API, enable two-step authentication again in order to keep your account secure and retain OBA status.

Troubshooting

If the template migration process fails, please refer to the following documentation for instructions on how to manually trigger a template migration: Template Migration.