Migrate Phone Number to a Different WABA

BSPs and businesses directly integrated with the WhatsApp Business API can now migrate a registered phone number from one WhatsApp Business Account (WABA) to another one at any time. After being migrated, a phone number keeps its 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 API 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 API can perform the phone number migration.

Overview

The migration process involves 3 main assets:

A source WABAA phone numberA 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 Facebook’s 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 Template Migration

A phone number’s High quality message templates are maintained throughout the migration process —in practice, they are copied to the destination WABA. These templates do not need to go through review again and can be sent immediately. Copying message templates from source WABA may cause the total number of templates in the destination WABA to go over the limit. This means that new templates cannot be added without deleting existing templates.

Low quality, rejected, or pending templates are not migrated. Any existing message templates in the destination WABA will not be overwritten.

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.

Exceptions

  • If you are using your phone number with the WhatsApp Business App, you need to delete your phone number from the app to use the same number on the API. In this case, you do not need to use migration. See Migrate App Phone Number to API for specific steps.
  • Businesses working with a BSP cannot switch to a direct integration using phone migration. Clients must work with a BSP directly to create a WABA to message on behalf of them, or they can create and share a WABA with the BSP by going through Embedded Signup on the BSP’s website —clients do not create a phone number during this process.
  • Message and chat history are not migrated with this process.
  • You cannot migrate several phone numbers at once, but APIs can be called for each number separately.

Summary

Migrated

Display name

Quality rating

Messaging limits

Official Business Account status

Any High quality message templates previously approved

Not Migrated

Low quality, rejected, or pending message templates.

Before You Start

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

AssetRequirements for Migration

Phone number

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.

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 WABAConsiderations 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.

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 method
  • Select Client’s Account in the Messaging for field, and
  • Enter 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.

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.

Examples

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:

NameDescription

cc

Required.

Numerical country code for the phone number being registered.

phone_number

Required.

Phone number being registered, 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 (WABA), go to Business Manager > Business Settings > Accounts > WhatsApp Business Accounts. Find the WABA you want to use and click on it. A panel will open up with information about the account, including the ID.

API call example:

curl -X POST \ 
'https://graph.facebook.com/v12.0/{whatsapp-business-account-id}/phone_numbers' \
  -d 'cc=1' \
  -d 'phone_number=6315551140' \
  -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:

NameDescription

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.

curl -X POST \ 
'https://graph.facebook.com/v12.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:

NameDescription

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/v12.0/{phone_number_id}/verify_code' \
  -d 'code={6-digit OTP 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

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.

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.

Troubleshooting

Errors

While trying to migrate a phone, you can encounter the following errors:

ErrorDescriptionSolution

2388103 - Please add this phone number in your WhatsApp account

This phone number is eligible to be added directly, and does not need to use phone migration APIs.

Add the phone number to your WhatsApp account from Business Manager directly, and proceed with registration.

2388103 - The WhatsApp account that this phone number is registered with is not set up correctly.

The source WABA must be approved, and its "messaging on behalf of" must be approved.

Work with the business that owns the source WABA to set up the account correctly or to deactivate it, and then retry migration.

2388103 - Your WhatsApp account must be approved

The destination WABA must be approved before you can migrate phone numbers.

Ensure business verification is completed, and WABA’s account review status is approved.

2388103 - Your WhatsApp account’s "Messaging For" request must be approved

The destination WABA’s "Messaging For" request must be approved by the client.

Ask your client to accept your "Messaging For" request.

2388103 - This phone number belongs to a different Business Manager account.

The source and destination WABAs must represent the same business.

Migrate your phone number into a WABA that is messaging for the same business as the source WABA.

2388012 - This phone number already exists in your list of phone numbers.

The phone number you are trying to migrate is already present in your WhatsApp account.

Try again with a phone number that is not already present in your WhatsApp account.

2388103 - There was an error migrating this phone number.

Something went wrong when trying to migrate your phone number.

Try again after some time. If that doesn’t work, contact support.

2388001 - Please confirm ownership of this phone number.

Certificate can be downloaded only after confirming ownership of a phone number that is being migrated.

In order to download the certificate and proceed with registration, request for a registration code and verify it.

2388091, 2388093 - This phone number isn’t eligible to receive/verify a registration code since it is not being migrated.

Phone ownership verification APIs are not available for this use case.

Verify and register the number using Enterprise Client v1/account and v1/verify APIs.

2388001 - Please ensure two-step authentication is disabled.

Two-step authentication must be disabled for this phone number.

Ask your client to reach out to the source WABA to disable two-step authentication before trying to migrate.

2388103 - Your WhatsApp account does not have a payment account.

Your WhatsApp account must have an active credit line in order to send messages after migration.

Follow steps here to set up a credit line for your WhatsApp account, or share your credit line using Business Manager or API.

FAQs

A number registered through the Embedded Signup flow can be migrated if business verification, WhatsApp account review, and display name reviews are completed, and the number is no longer in the unverified trial experience.

If you are using your phone number with the WhatsApp Business App, you need to delete your phone number from the app to use the same number on the API. In this case, you do not need to use migration. See Migrate App Phone Number to API for specific steps.
Message and chat history are not migrated with this process.

Insights for messages sent from this phone number before migration will be available in the Insights tab of the source WABA in Business Manager. Insights for messages sent from this phone number after migration will be available in the Insights tab of the destination WABA in Business Manager.

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.

After migration, the phone number is marked as "Transferred" on the source WABA. Certificates for that number cannot be downloaded. Transferred numbers can be deleted from the Business Manager.

The phone number can be migrated to any WABA (including back to the source WABA), if ownership is confirmed using the right registration code (and using the right pin, if two-factor authentication is enabled).

Please reset the two-factor authentication pin after migration to keep your account secure.

You cannot migrate several phone numbers at once, but APIs can be called for each number separately.
Businesses working with a BSP cannot switch to a direct integration using phone migration. Clients must work with a BSP directly to create a WABA to message on behalf of them, or they can create and share a WABA with the BSP by going through Embedded Signup on the BSP’s website —clients do not create a phone number during this process.
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.

Yes. To do that, businesses should follow these steps:

  1. Create a WABA using the same Business Manager account from the existing WABA by going through the Embedded Signup on the BSP’s website. Businesses do not need to add phone numbers —they can end the flow after WABA setup.
  2. If Business Verification is complete and WhatsApp business account reviews are approved, the WABA is ready.
  3. Since the WABA is already shared with the BSP, the BSP can perform phone migration to this WABA. BSPs should see Preparing Destination WABA for more information.

If the business’ Business Manager already has a WABA created from outside of Embedded Signup, the business can go through the Embedded Signup flow again to share this WABA with the BSP, before performing phone migration.

No. Low quality message templates are not migrated as part of this process.