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 Account, 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
Templates are automatically duplicated in the destination WABA and granted the same quality ratings and statuses as their source counterparts.
Only templates with both a status of APPROVED and quality_score of GREEN
are eligible for duplication. 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
Messages sent before migration is complete are charged to the old Solution Partner. Undelivered messages sent before migration is complete will be charged to the old Solution Partner if they are delivered after migration is complete.
Messages sent after migration is complete are charged to the new Solution Partner.
Downtime
Downtime doesn't begin until you perform the final step (registration). Until then, the business phone number can be used to send and receive messages without interruption.
Once you perform the final registration step, downtime begins and lasts until we complete template duplication.
Once completed, the business phone number can once again be used to send and receive messages, which will be associated with the customer's new WABA.
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.
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 payload.
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).
Related Articles
Deleting Phone Numbers
Limitations Only a business admin for the WhatsApp Business Account can delete a phone number. A number can not be deleted if the business has sent paid messages within the last 30 days using that number. If the business has sent paid messages in the ...Registering Phone Numbers
You can register a business phone number using the App Dashboard when completing the steps in our Get Started document. If you didn't register a number when completing the steps in the Get Started document, return to the App Dashboard, go to the ...Add your own business phone number to WhatsApp Cloud
Navigate to the Meta App that is set-up for WhatsApp by going to developers.facebook.com > My Apps > Select your App. If your phone number is currently registered with WhatsApp Messenger or the WhatsApp Business App, you need to first delete it. See ...Migrating from On-Premises API to Cloud API (or vice-versa)
This document explains how to migrate business phone numbers from On-Premises API to Cloud API. Note that migrating a business phone number from one API to another is not the same as migrating a number from one WhatsApp Business Account (WABA) to ...Display Name for WhatsApp Number
A business phone number display name is the name that appears in WhatsApp Manager It can also be displayed in WhatsApp chat thread headers, chat lists, and its profile, if the following conditions are met: The Meta business account that owns the ...