Drawing 1 · Interactive
Ready to delete the app account? Tick off the migration
8/8
ticked
- Required
- 5 / 5
- Optional
- 3 / 3
Ready for the one-way move
Every item ticked.
Ready for the one-way move. 8 of 8 ticked.
What is a Business App to API migration?
A Business App to API migration moves a phone number from the WhatsApp Business App onto the WhatsApp Cloud API permanently. A number can be registered to only one WhatsApp surface unless it uses coexistence, so the migration has two halves: you delete the WhatsApp Business app account on that number (Settings › Account › Delete my account), and then you add the freed number to a WhatsApp Business Account, verify it by SMS or voice code and register it on the API with a six-digit two-step verification PIN.
What you keep is the number itself — the one printed on invoices and saved in customers' phones. What you lose is the app account: its one-to-one chat history, groups, broadcast lists, labels, catalog and Status, and the ability to chat from the phone app on that number. Meta says that deleting and re-registering means existing messaging history is lost, so a chat backup before deletion is essential for your records, even though the API will not import it.
It is easy to confuse with two neighbours. Coexistence keeps the Business app and adds the Cloud API on the same number, with up to six months of one-to-one history synced. Phone Number Migration moves a number that is already on the API from one WhatsApp Business Account, or one partner, to another without deleting anything. A full app-to-API migration is the one-way door: choose it when you need what a platform-only number offers.
Key takeaways
- A Business App to API migration deletes the app account on a number so the number can run on the Cloud API alone.
- Chat history on the app account is lost when you delete it, so back it up first; the API does not import that backup.
- Meta says a deleted number can take up to 3 minutes to be released; messages sent meanwhile are queued.
- After migrating, the number cannot return to the app unless it is first deregistered from the Cloud API.
- If you want to keep the app, use coexistence instead: it adds the API without deleting anything.
Operating sequence
How does a Business App to API migration work?
Back up and export
Back up chats from the Business app, and export anything you need later — catalog items, labels, broadcast lists, quick replies and the profile text and photo — because none of it moves to the API.
Disconnect any coexistence provider
If the number is linked to a platform provider through coexistence, disconnect it first under Settings › Account › Business Platform. A number in use on both the app and the Cloud API cannot simply be deregistered.
Delete the app account
In the WhatsApp Business app, open Settings › Account › Delete my account and follow the prompts. Meta says the number can take up to 3 minutes to be released; messages sent to it meanwhile are queued.
Add and verify the number on a WABA
Add the number in WhatsApp Manager or through a provider's Embedded Signup, with a display name for review. Verify ownership with a code by SMS or voice call (
request_code, thenverify_code).Register it on the Cloud API
Call
POST /{PHONE_NUMBER_ID}/registerwithmessaging_productand a six-digitpin, which becomes the number's two-step verification PIN. Registration is limited to 10 attempts per number in 72 hours.Rebuild what customers see
Set the business profile, submit message templates, subscribe your webhook and add a payment method, then send a test template before switching campaigns and support to the new setup.
Implementation
A Business App to API migration in code
# 1. Ask for a verification code by SMS (or VOICE for a landline)curl -X POST "https://graph.facebook.com/v26.0/{PHONE_NUMBER_ID}/request_code" \-H "Authorization: Bearer {ACCESS_TOKEN}" \-d "code_method=SMS" -d "language=en_US"# 2. Submit the code the number receivedcurl -X POST "https://graph.facebook.com/v26.0/{PHONE_NUMBER_ID}/verify_code" \-H "Authorization: Bearer {ACCESS_TOKEN}" \-d "code={SIX_DIGIT_CODE}"# 3. Register on the Cloud API; the PIN becomes the two-step verification PINcurl -X POST "https://graph.facebook.com/v26.0/{PHONE_NUMBER_ID}/register" \-H "Authorization: Bearer {ACCESS_TOKEN}" \-H "Content-Type: application/json" \-d '{ "messaging_product": "whatsapp", "pin": "{SIX_DIGIT_PIN}" }'
Run these only after the app account is deleted and the number has been released.
Failure modes
Common mistakes with a Business App to API migration
Deleting before backing up
Deletion cannot be undone and the history goes with it. Back up chats and export catalog, labels and contacts first, and keep the backup somewhere other than the phone.
Choosing migration when coexistence would do
If the team still wants to chat from the phone and does not need more than 20 messages a second, the blue badge or platform calling, coexistence keeps the app and adds the API without the loss.
Migrating in the middle of trading hours
Between deletion and a working API setup the number cannot answer. Pick a quiet window and have the WABA, display name and templates prepared in advance.
Burning registration attempts
A wrong PIN or repeated register calls hit the 10-per-72-hours limit and lock the number out for three days. Store the PIN in a password manager before the first call.
Expecting customers to be told
WhatsApp does not announce the change. Customers keep the same number in their chats, but replies now arrive from your API tools, so brief your team and update any "chat with us on the app" instructions.
Specifications
A Business App to API migration: key facts and limits
- Number release after deletion
- Up to 3 minutes (Meta); messages queued meanwhile
- App chat history
- Lost when the app account is deleted
- Registration PIN
- 6 digits; becomes the two-step verification PIN
- Registration attempts
- 10 per number per 72 hours (error 133016)
- Throughput afterwards
- 80 messages/s to start; coexistence is fixed at 20
- Back to the app
- Only after deregistering from the Cloud API
Example: A Coimbatore textile wholesaler goes API-only
A Coimbatore wholesaler has used the Business app on its landline-linked mobile number for six years. It wants the Official Business Account badge and a 20-agent shared inbox, which rules out coexistence. On a Sunday evening the owner backs up chats, exports the catalog to a spreadsheet and deletes the app account. Four minutes later the number is added to the company's WABA, verified by voice call and registered with a new PIN. By Monday morning the profile, three utility templates and the webhook are live; customers who wrote overnight receive an order-update template once the team catches up.
Design intent
Why does a Business App to API migration matter?
The choice decides what your customer-facing number can do for years. A platform-only number starts at 80 messages per second and can be upgraded to 1,000, can apply for the Official Business Account blue verified badge, and can use platform calling and platform-managed groups — none of which a coexistence number gets. The cost is the app and its history. Done carelessly, a migration loses months of chats, leaves the number offline during a sale, or burns registration attempts on a forgotten PIN.
Recommended practice
Best practices for a Business App to API migration
- Do a dry run with a spare number first, so the team knows every screen before touching the real one.
- Prepare and submit the display name and two or three utility templates before deletion day.
- Use voice verification if the number is a landline or rarely receives SMS.
- Keep the exported catalog and quick replies — they make good first templates and chatbot answers.