Phone Number Migration to WhatsApp Cloud API

Benefits of migrating to WhatsApp Cloud API

WhatsApp Cloud API offers businesses a direct connection to WhatsApp's infrastructure as a self-service option, compared to going through WhatsApp partners (BSPs). Some benefits include:

• A more cost-effective option.
• A more reliable and stable connection to the platform.
• The ability to build custom integrations that fit your specific business needs.
• A flexible and scalable solution for businesses of all sizes.

What will be migrated?

The following elements can be migrated from a WhatsApp BSP to the WhatsApp Cloud API.

Can be migrated:

• Phone number associated with the account
• Any previously approved high-quality message templates
• Display name of the phone number
• Quality rating of the phone number
• Messaging limits
• Official WABA status

Cannot be migrated:

• Low-quality, rejected, or pending message templates

Pre-migration requirements

Two terms used throughout this document:

• Source WABA: the WhatsApp BSP you're migrating from.
• Destination WABA: the WhatsApp Cloud API you're migrating to.

Checklist to prepare before migrating:

• Existing Meta Developer App: if you don't have a developer app, create one in Meta Business Manager (MBM) to get started with WhatsApp Cloud API. This app must be created under the same business account (business ID) as the source WABA.
• Business ID: the source and destination WABAs must be associated with the same MBM or share the same business ID.
• Business Verification: the business ID must be verified.
• WABA Review Status: the review status of both the source and destination WABAs must be approved.
• Payment Method: a payment method must be configured for both the source and destination WABA.
• Two-Step Verification: two-step verification must be disabled on the phone number being migrated.

Once all of the above is complete, the migration process can continue.

Configuring phone numbers and WABA IDs

Meta designed WABA IDs to be non-migratable. Because of this limitation, a workaround is required. For phone number migration to occur, both source and destination WABA IDs must be under the same Meta Business Manager account — migrating a phone number only transfers that number between WABAs and won't allow any other changes. To successfully migrate a phone number:

1. Add a new number to the destination WABA: this generates a new WABA ID for the number you want to migrate to. You can skip this step if you have an existing WABA with a number that's no longer in use.
2. Delete the new number from the destination WABA: this vacates a slot for a number to be added. Alternatively, if you have an existing unused number, delete that one.
3. Once the number is deleted, migrate the current number to the new WhatsApp business.

API documentation for the migration process

These migration steps can currently only be executed by a developer or someone with a similar technical background. If you need help, contact our support team.

Step 1: Begin phone number migration

POST https://graph.facebook.com/{version}/{wabaId}/phone_numbers

Path parameters: version (the API version) and wabaId (the WhatsApp Cloud API WABA ID). To find your WABA ID, go to Business Manager > Business Settings > Accounts > WhatsApp Business Accounts and select the account — a panel with account information, including the ID, appears.

Header: Authorization: Bearer {Access Token}. The system user generates your access token in the WhatsApp Business Accounts tab of Business Manager.

Body parameters:

• cc — numerical country code for the phone number (no plus sign needed).
• phone_number — the phone number being migrated, without country code or plus symbol.
• migrate_phone_number — set to true to migrate the phone number.

A successful request returns 200 OK with the response:

{
    "id": "phoneNumberId"
}

Step 2: Request a code (PIN) to verify phone ownership

POST https://graph.facebook.com/{version}/{phoneNumberId}/request_code

Path parameters: version and phoneNumberId (the value returned in Step 1).

Header: Authorization: Bearer {Access Token}.

Body parameters:

• code_method — method of receiving the registration code. Supported values: SMS and Voice.
• language — language for the registration code (see Meta's language codes).

A successful request returns 200 OK with the response:

{
    "success": true
}

The code is sent to the phone number being migrated via the selected method.

Step 3: Verify the code

POST https://graph.facebook.com/{version}/{phoneNumberId}/verify_code

Use the 6-digit PIN received in Step 2 to verify ownership.

Header: Authorization: Bearer {Access Token}.

Body parameter: code — the 6-digit registration code received after Step 2.

A successful request returns 200 OK with the response:

{
    "success": true
}

This confirms phone ownership is verified.

Step 4: Register the phone number

POST https://graph.facebook.com/{version}/{phoneNumberId}/register

Header: Authorization: Bearer {Access Token}.

Body parameters:

• messaging_product — the messaging service used; here, whatsapp.
• pin — the 6-digit registration code received after Step 2.

A successful request returns 200 OK with the response:

{
    "success": true
}

The phone number is now registered to the WhatsApp Cloud API WABA, and you can send messages to your destination WABA.

The WABA ID is not migrated. The newly migrated number is associated with the WABA ID of the previously deleted number.

Step 5: Check the migrated phone number in the Meta Developer App

Verify a successful migration through the Meta Developer App:

1. Navigate to WhatsApp > Getting Started.
2. In the phone number dropdown, confirm that the number is present and accurately reflected.