Migrate a WhatsApp Number to the API: Keep vs Lose

The number on your shop sign, your invoices and your Google listing has years of customer chats behind it. You want it on the WhatsApp API so the team and your systems can use it properly. The provider's onboarding screen says "number already in use", and the fix it suggests is to delete the WhatsApp account on your phone. That sounds final, because it is.

This guide is the migration plan we would want before doing it: how to migrate a WhatsApp number to the API with the fewest surprises. It covers the three options (full migration, coexistence, or not migrating at all), what to export before you touch anything, the cutover in order, what customers notice during the gap, and how to reverse it if you change your mind.

Choose the kind of move first

There are three ways to get an existing number working with software, and only two of them involve Meta's API.

If the number is a WhatsApp Business app number and you want both the app and the API, read our WhatsApp coexistence guide before going further. The rest of this post is about full migration, the route for Messenger numbers, and for Business app numbers where you no longer want the app.

Before you touch anything: export what you need

Meta's documentation is direct about this: if you delete a WhatsApp Business app account and register the number on the Cloud API, your existing messaging history is lost. WhatsApp's help centre adds that deleting an account removes it from all its groups and also deletes its Google Account backup. So a backup inside WhatsApp is not a safe archive here.

Work through this list a few days ahead:

1. Export the chats you must keep. Use Export chat on each important conversation to save a text file, with media if you need it. Do the key customer threads and any group where agreements were made.
2. Save the contacts your team relies on, outside WhatsApp.
3. Note your groups. List groups you admin and make a colleague's number an admin first, so each group keeps an admin you trust.
4. Check the number is not banned. A banned number must be unbanned through WhatsApp's appeal process before it can be registered.
5. Confirm you can receive a code. You'll need an SMS or a voice call on this number during the cutover.
6. Prepare the API side. Have your app or provider account, display name, business profile, payment method and first templates ready, so the gap between deletion and sending is short.
7. Tell customers on status or in a broadcast that the number is moving to a new business service and replies may be slow for an hour.
8. Pick a quiet hour to cut over.

The cutover, step by step

1. Delete the WhatsApp account on the phone: Settings > Account > Delete my account, then follow the prompts. Meta notes that messages sent to the number are queued in the meantime, and that the number can take up to three minutes to become available.
2. Add the number to your WhatsApp account through your provider's signup, WhatsApp Manager or the App Dashboard's API Setup, with your display name.
3. Verify ownership with the code sent by SMS or voice call.
4. Register the number for Cloud API. Providers do this for you; if you are direct, it is one API call:

curl -X POST "https://graph.facebook.com/v23.0/PHONE_NUMBER_ID/register" \
  -H "Authorization: Bearer $WHATSAPP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "messaging_product": "whatsapp", "pin": "583920" }'

5. Confirm it is connected before announcing anything:

curl -G "https://graph.facebook.com/v23.0/PHONE_NUMBER_ID" \
  --data-urlencode "fields=status,code_verification_status,name_status" \
  -H "Authorization: Bearer $WHATSAPP_TOKEN"

You want "status": "CONNECTED". Use the current Graph API version from Meta's changelog in both calls.

6. Send a test from a colleague's phone, reply inside the 24-hour window, and check your webhooks fire.

If registration returns 133015, the deletion has not finished; Meta says to wait five minutes and retry. Do not hammer the endpoint: 10 register attempts in a moving 72 hours triggers error 133016 and a 72-hour block, the worst possible outcome mid-cutover.

About the PIN: it is the platform's two-step verification PIN for this number, unrelated to any PIN you used in the app. Meta is phasing it out for eligible numbers as part of its new account model, yet the register call still expects six digits, so keep sending one and store it with your other secrets.

What customers notice during and after

From the customer's side, the number never changes. During the gap, messages they send are queued rather than lost, per Meta's migration note. After cutover:

• Your profile shows the display name and business profile you set on the platform. The name may only appear at the top of chats after Meta's display name review.
• Old chat history stays on the customer's phone, but your side starts empty.
• You cannot message anyone first with free text any more. Outside the 24-hour customer service window, every business-initiated message must be an approved template. Our guide to the 24-hour window explains what opens and refreshes it.
• Groups are gone from your side, because the account left them when it was deleted. The official Groups API can create new groups for eligible businesses, but cannot rejoin old ones.

Rolling back, and moving between providers later

If the API turns out to be the wrong fit, you can take the number back to the app. Deregistering makes it unusable with the Cloud API; it does not delete the number or its message history from your account.

curl -X POST "https://graph.facebook.com/v23.0/PHONE_NUMBER_ID/deregister" \
  -H "Authorization: Bearer $WHATSAPP_TOKEN"

Deregistration has the same 10-per-72-hours limit. Deleting the number from your WhatsApp account entirely is done only in WhatsApp Manager, by a business portfolio admin, and is blocked for 30 days after the number last sent a paid message. Plan for that if you are leaving in a hurry.

Changing providers later used to mean a number migration between accounts. Under Meta's new account model, which reached all businesses by mid-October 2026, migrating a number between partners is no longer supported. Instead you share your WhatsApp account with the new partner, the number stays put and conversations continue. Older guides that walk through migration APIs and error 2388103 describe the previous model. Our guide to switching WhatsApp API providers covers that process.

Where Tenashi fits

Many teams start this migration because they want the whole team on the business number, not because they need templates or the green tick. If that is you, you may not need to migrate at all. Tenashi links your existing WhatsApp or WhatsApp Business number with a QR scan, as a linked device. Your chat history imports, your groups stay, the phone keeps working, and the team gets a shared inbox with a CRM, assignments, notes and scheduled sends. Messages typed on the phone show up in the inbox too.

The trade-off is that Tenashi is not Meta's official platform. You don't get templates, interactive buttons or a green tick, sends are paced, and WhatsApp can still ban numbers that spam. The phone that owns the number should stay online regularly, because WhatsApp logs out linked devices after long offline periods. For the full set of options, see the complete guide to the WhatsApp API.

See every feature · Get started

FAQ

Will I lose my chat history if I migrate my number to the API?

With a full migration, yes. Meta says existing messaging history is lost when you delete a WhatsApp Business app account and register the number on Cloud API, and deleting the account also removes its Google backup. Export important chats first. Coexistence avoids this by syncing up to 180 days of history to your provider, if you allow it.

Can I move my number back to the WhatsApp Business app?

Yes. Deregister the number from Cloud API with the deregister endpoint or ask your provider to do it, then set it up again in the app. You will start with no history in the app. Deregistration is limited to 10 attempts per number in a moving 72 hours, so do it once and deliberately.

What happens to my WhatsApp groups?

Deleting the WhatsApp account removes it from every group, so a fully migrated number is no longer in your old groups. Hand admin rights to a colleague before you delete. Meta's Groups API can create new invite-only groups for eligible businesses, but it can't rejoin groups or read them. Coexistence and linked-device tools keep the groups.

How long does the migration take?

The cutover itself is short. The account deletion can take up to three minutes to free the number, and verifying and registering take minutes more when nothing goes wrong. Plan an hour of slow replies to be safe. The preparation, exporting chats and getting your display name and payment method ready, is what takes the time.

Do I need a new SIM or phone for the API?

No. The Cloud API is hosted by Meta, so there is no phone running WhatsApp for that number after migration. You only need to receive the verification SMS or voice call on the existing line. The SIM can stay where it is and keep making normal calls and texts.

---

Decide between full migration, coexistence and not migrating before you delete anything, because only one of them is hard to undo. If keeping your number, history and groups matters most, see how Tenashi works.