BSPs and businesses directly integrated with the WhatsApp Business Platform can migrate a registered phone number from one WhatsApp Business Account (WABA) to another. Migrated phone numbers keep their display name, quality rating, messaging limits, 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 BSPs and want to switch to a different provider.
- They are using their own implementation and want to switch to a BSP.
Only Business Solution Providers (BSPs) and businesses directly integrated with the WhatsApp Business Platform can perform the phone number migration.
Overview
The migration process involves 3 main assets:
| A source WABA | A phone number | A destination WABA |
|---|---|---|
| The account the phone number is currently registered to. | The number that will be migrated. | The account the number will be migrated to. |
Phone migration is always initiated by the BSP 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
Until migration is completed by registering the phone number on the destination WABA, the source WABA can continue to send and receive messages without disruption in service. After migration is complete, the destination WABA can start sending messages immediately, without any 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.
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.
Billing Migration
Messages sent before migration are charged to the source business. Messages sent after migration are charged to the destination business. Messages sent from the source, and are not delivered before migration, are still charged to the source business when they get delivered.
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.
Summary
| MigratedDisplay nameQuality ratingMessaging limitsOfficial Business Account statusAny High quality message templates previously approved | Not MigratedLow quality, rejected, or pending message templates. |
Before You Start
To be eligible for migration, a business’ assets must meet the following criteria:
| Asset | Requirements for Migration |
|---|---|
| Phone number | Must be currently registered with the source WABA.If two-factor authentication was ever enabled for this number, it needs to be disabled. This means the source WABA owner needs to disable the two-factor 6-digit pin that was previously set.The phone number’s owner is responsible for reaching out to the source WABA’s owner. |
| Source WABA | Must have Business Verification completed and approved.WABA’s review status must be Approved. |
| Destination WABA | Must have Business Verification and WABA review completed and approved.Must have a payment method set up.Must message on behalf of the same business as the source WABA.Must represent the same business as the source WABA, meaning: the ID of the business that owns the source WABA or the ID of the business that the source WABA is messaging for must match the ID of the business that owns the destination WABA or the ID of the business that the destination WABA is messaging for. |
| Webhooks | Phone numbers on Cloud API only At least one app must be subscribed to webhooks for the destination WABA. See Webhooks in Cloud API. |
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 BSP 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:
| Type of WABA | Considerations for BSPs performing migration |
|---|---|
| Existing WABA | Confirm that the existing (destination) WABA is set up to message for the same Business Manager ID as the source WABA, and also has a payment method set up. If the source WABA is on Cloud API, make sure at least one app is subscribed to webhooks for the destination WABA. |
| New WABA created by a BSP messaging for a client | When creating a new WABA in the Business Manager, a BSP must:Enter an Account Name for client (WABA Name)Select a payment methodSelect Client’s Account in the Messaging for field, andEnter the client’s Business Manager ID — see Find Your Business ID in Business Manager. This must be the same ID that the source WABA is connected to.BSPs can then instruct their clients to accept the Messaging For request sent to their Business Manager. To guide your customers, see Create Your WhatsApp Business Account With WhatsApp Business Solution Providers, Approve messaging on behalf of your business. Once the request has been accepted, the destination WABA is ready for phone migration. If the source WABA is on Cloud API, make sure at least one app is subscribed to webhooks for the destination WABA. |
| New WABA created by a client and shared with a BSP via Embedded Signup | This type of WABA is created once a client goes through the Embedded Signup flow on the BSP’s website. To guide your customers, see Create Your WhatsApp Business Account With WhatsApp Business Solution Providers, Embedded Signup. During the Embedded Signup flow, instruct the client to:Select the same business as the one that owns their existing WABA.Do not add a phone number via signup flow —we’ll be using the migration API for this. Clients can finish the Embedded Signup flow after creating their WhatsApp Business Account.Use Embedded Signup APIs to get the WABA created by the client, add system users, and set up a payment method for the WABA. Since the WABA is already shared with the BSP, the WABA is ready for phone migration. Reminder: The migration only happens if the client’s business has completed Business Verification. If the source WABA is on Cloud API, make sure at least one app is subscribed to webhooks for the destination WABA. |
Get Started
All migration calls are made to the endpoint with the destination WABA’s ID. Phone migration is always initiated by the BSP or business that owns the destination WABA.
Step 1: 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:
| Name | Description |
|---|---|
cc | Required.Numerical country code for the phone number being registered. |
phone_number | Required.Phone number being migrated, without the country code or plus symbol (+). |
migrate_phone_number | Required.To migrate a phone number, set this to true. |
To find the ID of a WhatsApp Business Account, go to Business Manager > Business Settings > Accounts > WhatsApp Business Accounts. Find the account you want to use and click on it. A panel opens, with information about the account, including the ID.
API call example:
curl -X POST \
'https://graph.facebook.com/v15.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 2: 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:
| Name | Description |
|---|---|
code_method | Required.Method of receiving the registration code. Supported values: SMS and VOICE. |
language | Required.Language in which you want to receive the registration code. See language codes. |
A sample call looks like this:
curl -X POST \
'https://graph.facebook.com/v15.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:
| Name | Description |
|---|---|
code | Required.6-digit registration code received after making the /PHONE_NUMBER_ID/request_code call. |
For example:
curl -X POST \
'https://graph.facebook.com/v15.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 3: 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 Phone Number Register endpoint to register the phone number again. See Register the business phone number.
Step 4 for OBAs: Re-Enable 2-Factor Authentication
This step is only Official Business Accounts (OBA). To keep your account secure and to retain OBA status, re-enable the two-factor authentication pin after migration.
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.
