WhatsApp Business API Number Migration: Moving a Number Between Providers Without Losing Your Display Name or Quality Rating
Switching WhatsApp Cloud API providers — or moving a number off the WhatsApp Business app — is not a simple “copy the number over” job. Done in the right order, migration can keep your display name, quality rating, template limits, and approved templates intact. Done in the wrong order, you can lose your message history, reset your quality rating, or lock the number for weeks.
This guide explains what migration involves and where projects stall. The exact registration and cut-over steps are the part we handle for you — a mistake here is expensive to undo.
Businesses ask about number migration for one of three reasons: they are unhappy with their current Business Solution Provider (BSP) and want to move to another, they built on the free WhatsApp Business app and have outgrown it, or they are on a legacy setup that Meta has retired. Each path has different rules, and the differences are exactly where people get stuck.
The three migration scenarios — and why they are not the same
Provider to provider (BSP switch)
Moving a number from one provider’s WhatsApp Business Account (WABA) to another, usually through Embedded Signup. This is the “cleanest” path: because the phone number itself is not changing, Meta preserves the display name, quality rating, messaging (template) limit, Official Business Account status, and approved high-quality templates. Registration happens instantly, so messaging continues without interruption — if every prerequisite is met first.
WhatsApp Business app to Cloud API
Here the rules change sharply. To use an existing Business app number with the Cloud API you must either delete the account (your existing message history is lost, and you can no longer use that number in the Business app unless you deregister it) or onboard through a provider that supports Business-app onboarding — in which case history is preserved and both can run at once. That second path is essentially WhatsApp Coexistence, and choosing the wrong one is irreversible.
Legacy / On-Premises API to Cloud API
The On-Premises API has been retired — since 1 July 2024, business phone numbers can only be registered for use with the Cloud API, and older on-prem versions can no longer message WhatsApp users. Anyone still on a self-hosted or deprecated stack has to move, and the migration has to be sequenced so the number is freed and re-registered correctly rather than getting stranded mid-move.
What actually carries over in a provider-to-provider move
This is the single most important thing to understand before you switch BSPs, because a badly executed migration can throw away assets that took months to earn. In a correct Embedded Signup migration between WABAs:
Preserved
- Display name (no re-approval if it is already approved)
- Quality rating on the number
- Template / messaging tier limit
- Official Business Account (OBA) status
- Approved, high-quality message templates
Resets or needs care
- Template quality ratings restart at UNKNOWN for the first 24 hours
- Templates must be duplicated to the new WABA before registering to avoid template downtime
- Two-step verification must be turned off to migrate, then a new PIN set on the new WABA
- Webhooks must be re-subscribed on the destination app
The takeaway: the number keeps its hard-won reputation, but only when templates and webhooks are moved in the right sequence. Get the order wrong and you can trigger avoidable template downtime or a fresh quality-rating review on your sends.
The prerequisites that block most migrations
Meta will not let you complete a provider-to-provider migration until the client side is fully in order. The four that stop people cold:
- Verified Meta Business Account. The business behind the number must already be verified — migration is not the time to discover verification was never completed.
- Approved WABA with a valid payment method. The existing WhatsApp Business Account has to be in good standing and have billing attached.
- Two-step verification disabled. You cannot finish the remaining steps until it is switched off on the number — and a forgotten PIN here stalls everything.
- Approved display name, no pending change. The name status must be APPROVED with no name-change request in flight, or the number will not move.
Note that test numbers cannot be migrated at all, and a number that is banned has to be appealed and unbanned before anything else can happen.
How a clean migration is sequenced (high level)
Confirm eligibility
Business verification, WABA status, payment method, display-name status and two-step verification are all checked before touching anything live.
Move the templates first
Approved templates are duplicated onto the destination WABA ahead of registration so there is no gap in what you can send.
Complete Embedded Signup
The number and display name are onboarded to the new provider’s WABA — the same Embedded Signup and Tech Provider flow used for scaled onboarding.
Re-wire webhooks and credit line
The destination app is subscribed to the number’s events and the billing credit line is shared, so messages route correctly the moment it is live.
Register for Cloud API
The number is registered with a new two-step PIN. Registration is instant, so sending and receiving continue without a visible outage.
We deliberately keep the exact endpoint calls, timing, and rollback plan out of this article. That sequencing — and knowing what to do when a step fails mid-migration — is the work, and it is where a DIY attempt usually goes wrong.
The errors and traps that derail number migrations
“Number already registered”
A number already in use with WhatsApp cannot be registered elsewhere until it is deleted or released first. On the Business app path, deletion wipes your history — so the decision of whether to delete has to be made before you start, not after.
The two-step PIN
A two-step verification PIN is required to register, change, or delete a number, and it cannot be disabled through the API. A lost or unknown PIN is one of the most common reasons a migration freezes halfway.
The 30-day paid-message lock
If your path requires deleting the number, be aware a number cannot be deleted if it has sent paid messages in the last 30 days — you have to wait out the window from the date of the last paid message. That single rule can push a “quick” switch out by a month.
Why businesses hand this to us
A number migration touches billing, reputation, message history, and live customer conversations at the same time. There is no undo button if you delete the wrong account or register in the wrong order. We map the correct scenario for your setup, confirm every prerequisite is genuinely in place, move templates and webhooks in the right sequence, and cut the number over so your team keeps sending and receiving throughout. If your current provider is holding your number hostage or you have simply outgrown the WhatsApp Business app, that is exactly the situation we prepare and execute.