Migrating Phone Numbers

This document describes phone migration and related concepts.

What is Migration?

In the context of the WhatsApp Business Platform, migration refers to the process of transferring a phone number from one WhatsApp Business account to another, without losing its messaging history, display name, or quality rating. This process is typically used when:

This process is typically used when:

• A business switches from one Business Solution Provider (BSP) to another

• A business wants to move a number from one WhatsApp Business Account (WABA) to another

• A business wants to change the currency of a WABA

Migration is only required if a phone number is already registered for the WhatsApp Business API.

The WABA currently hosting the number is called the source WABA, while the WABA receiving the number is called the destination WABA.

If the number is being used on the WhatsApp Business App, you must either 1) onboard the number using Coexistance or 2) delete the WhatsApp Business App account before proceeding to register the number for the WhatsApp Business API.

If the number is being used on the consumer WhatsApp app, there is no API migration process; instead, delete the WhatsApp consumer App account before proceeding to register the number for the WhatsApp Business API.

Migration Scenarios

The scenarios below outline when a phone number registered for the WhatsApp Business API may need to be migrated or reassigned. Migrations involve moving the number between BSPs or WABAs. Internal configuration changes happen within the 360Dialog platform.

Scenario	Description	Type
Migrate a phone number to 360Dialog	Transfer a number from another BSP to 360Dialog while retaining its API registration.	Migration
Migrate a number to a new WABA (with 360Dialog)	Transfer a number from one WhatsApp Business Account to another under 360Dialog.	Migration
Migrate a number to an alternate BSP	Transfer a number from 360Dialog to a different BSP.	Migration
Migrate a client to a new Partner (with 360Dialog)	Transferring all Business numbers to another 360Dialog integration Partner. (Partner Change)	Configuration Change
Migrate a WABA to a new Partner (with 360Dialog)	Transferring 1 WABA and any contained numbers to another 360Dialog integration Partner.	Migration
Moving numbers between Business Managers	Migrate a number from one Meta Business Manager account to another.	Migration
Hosting type Change (On-premise API to Cloud API)	Migrate a number from On-Premise -> Cloud API	Configuration Change

Impact on Assets

Asset	Migration	Configuration Changes
Display Name	✅ Yes	✅ No loss
Quality Rating	✅ Yes	✅ No loss
Messaging Limits	✅ Yes	✅No loss
Official Business Account Status	✅ Yes	✅No loss
Uploaded Media	✅ Yes	✅No loss
Approved High-Quality Message Templates	✅ Yes	✅No loss
Low-Quality, Rejected, or Pending Message Templates	❌ No	✅ No loss
Catalogs	❌ No	✅ No loss
Message and Chat History	❌ No	✅ No loss

Templates

Templates are automatically duplicated in the destination WABA and initially granted the same status as their source counterparts.

After duplication however, templates are re-checked to ensure they are correctly categorized according to Meta guidelines. This may result in some duplicated templates having their status set to REJECTED.

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.

Note that template quality ratings are not duplicated. All duplicated 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.

Billing

Messages delivered before the 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 delivered after migration is complete are charged to the business customer.

Limitations

• Test business phone numbers issued by WhatsApp cannot be migrated.

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