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 API account (or provider) to another, without losing its messaging history, display name, or quality rating.

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

• A business moves from an On-Premises API setup to a Cloud API setup

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

If the number is only being used on the WhatsApp Business App or the consumer WhatsApp app, there is no API migration process; instead, the number would first need to be deregistered from the app and then registered for the 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	Moving a number from another BSP to 360dialog while retaining its API registration.	Migration
Migrate a number to a new WABA (with 360dialog)	Moving a number from one WhatsApp Business Account to another under 360dialog.	Migration
Migrate a number to an alternate BSP	Transferring a number from 360dialog to a different BSP.	Migration
Migrate a number from On-Premise to Cloud API (with 360dialog)	Switching a number’s hosting type from On-Premise API to 360dialog Cloud API.	Configuration Change
Migrate a number to a new Partner (with 360dialog)	Transferring the management of a number’s WABA to another 360dialog Partner. (Partner Change)	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.

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