Migrating Phone Numbers Between WhatsApp Business Accounts via Embedded Signup

This document describes how to use Embedded Signup to migrate business phone numbers from one WhatsApp Business Account (WABA) to another.

Customers can migrate their business phone numbers between WhatsApp Business Accounts (WABAs) and retain their display names, quality ratings, template messaging limits, Official Business Account statuses, and approved, high-quality templates. Migration typically is only performed when a customer wants to move their business phone number from one Solution Partner to another.

To perform a migration for a customer, you have two options: migration via Embedded Signup, or programmatic migration.

Migration via Embedded Signup is simpler and is the preferred solution because it can be initiated by your customers, automatically generates and grants ownership of all necessary assets, grants your app access to those assets, and requires fewer API calls.

Programmatic migration must be initiated by you and involves more API calls, as you must verify that dependent assets are configured correctly, must generate all new required assets on your own, and must associate them with other assets. For this reason, programmatic migration is only recommended if you will be working with the 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 programmatically, see our Migrating Numbers Between WhatsApp Business Accounts Programmatically document.

How It Works

Customers can use your implementation of Embedded Signup (version 2) to start the migration process. Embedded Signup will prompt customers for their business phone number and a new destination WhatsApp Business Account (WABA).

When the customer completes the flow, Embedded Signup generates their new WABA, associates it with their Meta business portfolio, grants your app access to the WABA, then returns the newly created WABA ID and the business phone number ID.

You must capture these IDs and use them with the API to share your credit line, subscribe to webhooks, and register the number for use with Cloud API. Once you complete the final step (registration), the business phone number is reassociated with the destination WABA and the number can then be used to send and receive messages again.

Since the customer's business phone number is not changing, its display name, quality rating, messaging limit, and Official Business Account status are all preserved.

In addition, all eligible templates are automatically duplicated in the destination WABA and granted the same statuses as their source counterparts, and all media uploaded on the customer's business phone number can continue to be used.

WhatsApp Business Accounts

Embedded Signup automatically generates the customer's new WABA, associates it with their Meta Business Account, and grants your app access to the WABA.

Templates

Billing

Template Downtime

Business phone number registration happens instantly, therefore you can continue to send and receive messages without interruption.

However, template duplication takes time, therefore you will not be able to use affected templates until they are migrated.

To avoid this downtime, you can begin template migration first, before phone number registration.

Rate Limits

Template duplication triggered automatically as part of the migration process does not count against your rate limit. API calls that you perform, however, do count against the limit.

Limitations

• Test business phone numbers issued by WhatsApp cannot be migrated.
• Migrated business phone numbers can only be registered for use with Cloud API.
• Message history and uploaded media will not be migrated if the source WABA is on On-Premises API.
• 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 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.

Requirements

Customers

Ask the customer who owns the business phone number to confirm that they meet the following requirements. They can do this using the Meta Business Manager, if they own their WABA, by going to WhatsApp Accounts > (their WABA name) > Settings. If they do not own their WABA, they must ask their BSP to confirm.

• Their Meta Business Account must have a verified status.
• Their existing WABA must have a status of approved.
• Their existing WABA must have a valid payment method attached (in Payment Settings).
• Their business phone number must have two-step verification disabled. Customers who own their WABA can use the WhatsApp Manager to disable two-step verification on their number, otherwise they must ask their Solution Provider to disable it for them.

Solution Providers

At least one app must already be subscribed to webhooks on the destination WABA (see Webhooks), and you must be using Embedded Signup version 2 with session logging enabled.

Migration Steps

Step 1: Instruct Customer to Disable Two-Step Verification

If you haven't already done so, instruct your customer to use the WhatsApp Manager to disable two-step verification on their business phone number (or to ask their current Solution Provider to disable it for them).

You cannot complete the remaining steps until two-step verification is disabled.

Step 2: Surface Embedded Signup

Direct the customer to access your implementation of Embedded Signup (version 2) and to supply their business phone number and its display name when prompted for them in the flow.

Step 3: Capture Asset IDs

When the customer completes the flow, capture the business phone number ID and new WABA returned in the message event.

Step 4: Share Your Credit Line

Share your credit line with the WABA just like you normally would after onboarding a customer via Embedded Signup.

Step 5: Subscribe webhooks

Subscribe your app to webhooks on the customer's new WABA.

Step 6: Register the phone number for Cloud API

Register the business phone number for use with Cloud API (you cannot register a migrated business business phone number for use with On-Premises API).

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.