Moving a number from the WhatsApp Business app to the Cloud API

Two operations share the name migration here. One deletes the WhatsApp Business app account on the number and registers the bare number with Cloud API, which costs you the messages on it. The other has a partner onboard the number while the app keeps working, and its prerequisites are mostly not yours to satisfy. Establish which one you are on first.

Which route you are actually on

Meta’s migration page gives a Business app number two options: delete the account, or onboard through a partner who supports business app number onboarding. It spells out the cost of the first, in a sentence we quote in full elsewhere on this site. Deleting loses the existing messaging history and stops the number working with the Business app again unless it is deregistered from Cloud API. Notice which half carries a condition. The lockout does. The history loss does not.

Before either route, the page gives one instruction: “Remember to back up your chat history from the WhatsApp Business App.” That export is the only copy the pages cited here offer you.

The partner route is the one Meta describes as lossless:

If you onboard via a partner who supports business app number onboarding, you will be able to use both the WhatsApp Business app and the partner’s app concurrently, and your messaging history will be preserved.

Prerequisites for the route that keeps history

Meta’s onboarding page reads as questions for a vendor, not a checklist for you. It requires “You must already be a Solution Partner or Tech Provider”, “You must use Embedded Signup with session logging”, and “Your webhook callback must be able to successfully accept and digest webhooks.” Those three are the vendor’s to satisfy, not yours.

Exactly one item is on your side: “The business customer must use WhatsApp Business app version 2.24.17 or higher”. Check it first.

The delete route, in order

The migration page gives the steps and two timings. Open the app, go to Settings then Account, and “Select Delete my account.” While the number is in limbo, “Messages sent to this phone number will be queued in the meantime.” Then “It may take up to 3 minutes for the disconnected number to become available”, after which “Once the number is available, follow the instructions to Add a Phone Number”.

Adding is not the end. The registration guide: “To use your business phone number with Cloud API you must register it.” It also rules out the console: “You can only register a number via the API”, not WhatsApp Manager or the App Dashboard. So the sequence is add, verify ownership, register by API call, and only the first two are clickable.

The onboarding route, and the clock on it

Confirmation happens inside the app, by the person holding the phone, who must “Tap the Confirm button in the app to give the business the option to share their chat history with you.” Sharing the history is a choice made at that moment.

Then a short deadline starts:

After you onboard the business customer, you have 24 hours to synchronize their contacts and messaging history, otherwise they must be offboarded and complete the flow again.

Each synchronisation runs once. Meta repeats the warning for contacts and for history: “You can only perform this step once. If you need to perform it again, the customer must first offboard, then complete the Embedded Signup flow again.” Its advice to partners: “advise them to keep the WhatsApp Business app open to facilitate the synchronization process”, since “Onboarding and synchronization can take several minutes”.

One step disappears here. Partners are told to “skip the phone number registration step”, because the number is already registered. That is why nobody asks you for a verification PIN on this route, and it matters below.

What the app loses, in Meta’s rows

Meta’s feature comparison describes the app after onboarding. Left column is Meta’s wording, right is our reading.

Meta’s row	What it means on the day
“All contacts with a WhatsApp number can be synchronized.”	Contacts carry over. Anyone without WhatsApp does not.
“Message Edit/Revoke is now supported.”	One gain: editing and revoking work.
“View once messages will be disabled for all individual (1:1) chats”	Disabled, not paused, with no documented way to keep them.
“Business will not be able to create new Broadcast lists.”	Existing lists survive read-only. New ones cannot be made.

Live location messages go the same way, and history synchronisation is bounded to the most recent six months.

Two-step verification and the display name afterwards

On the delete route, registration is where two-step verification gets decided. The registration guide says “Meta enforces two-step verification during account creation to add an extra layer of security to your accounts”, and the PIN parameter branches on prior state. With it already on: “set this value to your number’s 6-digit two-step verification PIN.” Without: “set this value to a 6-digit number”, which then becomes the number’s PIN.

Changing the display name has a loop attached. Approval comes before the API call: “The phone_number_name_update webhook confirms when the name change is approved”, and “Re-registering before approval has no effect, so wait for approval first.”

Both describe the register path. On the onboarding route that step is skipped, and neither page we read states what the two-step verification state or display name of a coexistence number is afterwards. We have not tested it and will not assert it.

What deregistering does, and what it does not undo

Narrower than it sounds. The registration guide warns that “Deregistering a business phone number makes it unusable with Cloud API and disables local storage on the number, if it had been enabled.” It also states what survives: “Deregistration does not delete a number or its message history.” The deregister reference says the call “removes the phone number from the WhatsApp Business Platform and makes it available for re-registration if needed”, and the way back is explicit: “To use the number again, you must re-register it.”

Two traps. The endpoint refuses coexistence numbers: “You cannot use the Deregister API to deregister a business phone number from Cloud API if it is already in use with both Cloud API and the WhatsApp Business app.” The route out is in the app, at Settings then Account then Business Platform, using the Disconnect Account button, which fires a partner-removed account update. The reference agrees from its own side, listing “Cannot deregister phone numbers associated with SMB accounts” among its constraints.

And you get ten attempts: “Requests to the deregistration endpoint are limited to 10 requests per business number in a 72-hour moving window”, past which “the API returns error code 133016” and a 72-hour block. Registration carries the same limit.

What is reversible, and what Meta does not address

Documented as reversible: deregistering, by re-registering. Local storage, by deregistering and registering again. A display name, through approval then re-registration. A disconnected coexistence account, by re-onboarding to the same partner, which Meta gives its own reconnect event.

Not addressed on any page cited here: whether history deleted on the delete route can be recovered, whether labels, quick replies and greeting settings return when a number is deregistered and used in the app again, and how long that takes. The documentation is silent on all three.

The answer

If the messages matter, the delete route is not a migration, it is a replacement plus a backup file. Go through a partner who supports business app onboarding, check the app version first, and keep somebody free to finish synchronising inside a day. Choosing that partner by what their platform documents rather than what their homepage claims is the same exercise as picking review management software.