WhatsApp Coexistence · 2026
How to Migrate Your Existing WhatsApp Number to the Business API Without Losing Chats
If your customers already know your WhatsApp number, the first question isn't "how do I get the API?" It's "how do I add the API without changing the number, or losing the conversations, my team already relies on?" There's an official way to do exactly that, and it isn't a classic migration.
By On Cloud API team · Updated
- Can I keep my number and my chats?
- Coexistence vs an API-only migration
- What do you need before you start?
- How do you connect the number?
- What happens to your chat history?
- What changes in the WhatsApp Business app?
- Limits, billing and the 24-hour window
- Mistakes to avoid
- Does your country matter?
- How On Cloud API helps
- Frequently asked questions
Can I connect my existing WhatsApp Business number to the API and keep my chats?
Quick answer: Yes, with WhatsApp Coexistence. It connects the number you already use in the WhatsApp Business app to the Cloud API, so the app keeps working and your one-to-one chats stay. If you approve it, up to six months of chat history can sync to your new inbox. An API-only migration, by contrast, takes the number off the phone app.
Meta calls this onboarding WhatsApp Business app users to the platform, and partners like us call it Coexistence. The business keeps sending one-to-one messages from the app, while software, automation and a team inbox use the API on the same number, and Meta keeps the messages in sync between both.
- Coexistence keeps your number and the Business app. Nothing gets deleted to make it work.
- Up to six months of one-to-one chats and your contacts can sync, only if you approve sharing during setup.
- Group chats don't sync, and a few app features are switched off or become read-only.
- The number is capped at 20 messages a second on the API while it stays on the app.
- Messages you send from the app stay free. Messages sent through the API are charged per message.
What's the difference between Coexistence and an API-only migration?
Coexistence keeps the phone app alive on the number; an API-only migration doesn't. Pick Coexistence if your team still likes the app, or you want to automate gradually. Choose API-only if you want everything to run through software from day one.
| Question | Coexistence | API-only migration |
|---|---|---|
| Same phone number | Yes | Yes |
| WhatsApp Business app on the number | Keeps working | No longer the way you use that number |
| Old chats | Stay in the app; up to 6 months can sync to your inbox | Don't assume they move across |
| Automation, chatbots, CRM | Yes | Yes |
| Best for | Teams moving from manual chat to automation step by step | Teams ready to run the number fully through software |
If you're still deciding whether you need the API at all, read WhatsApp Business App vs WhatsApp Business API first.
What do you need before you start?
A number already on the WhatsApp Business app, a recent app version, and a Meta-approved partner. Meta's documented requirements are short:
- The number must be registered on the WhatsApp Business app, not the regular WhatsApp app.
- The app must be version 2.24.17 or higher.
- You need a Meta business portfolio for your business.
- You onboard through a Solution Partner or Tech Provider using Meta's Embedded Signup, the sign-up flow that connects your number to a platform. On Cloud API is a Meta Verified Tech Provider.
Set up your destination first, meaning the inbox or software that will receive messages. Don't delete or re-register anything on the old account.
How do you connect your existing number step by step?
Choose the existing-number option in Embedded Signup, verify the number, decide on chat history, and test both sides. The whole flow takes minutes, but the testing is what saves you later.
- Confirm your starting point. The number is active on the Business app, and you've chosen Coexistence rather than an API-only move.
- Start Embedded Signup from your provider and pick the option to use your existing WhatsApp Business app number, not a new number.
- Enter the number and verify it. Meta asks you to confirm in the Business app and enter a verification code, so keep the phone in your hand.
- Decide on chat history. The app asks whether to share your chat history with the business platform. Choose deliberately, and note that you decide at setup time.
- Finish the flow. Your account is converted for API use, and the number keeps the same account ID.
- Test both directions. Send from the app, send from the inbox, reply from each, and check that webhooks and automation fire before you switch the team over.
Tip: do the switch while your support team is online and watching the number. Most migration problems are discovered after launch, when nobody tested the real customer journey end to end. For the developer side of connecting the API, see our Cloud API setup guide.
What happens to your chat history?
Your chats stay in the app, and up to six months of one-to-one history can sync to your inbox if you approve it. "Keeping your chats" means two different things here, and it's worth separating them.
| What | What to expect |
|---|---|
| Chats in the Business app | Stay where they are and keep working |
| History in your new inbox | One-to-one messages from up to the last 6 months, if you approve sharing |
| Contacts | Contacts with a WhatsApp number can sync |
| Group chats | Not synced |
| Photos and files in old chats | Limited. Meta only sends media for messages within 14 days of onboarding |
| CRM records | Old chats don't become CRM tickets by themselves. Plan a separate import or mapping |
Sync happens in phases after onboarding, so the history arrives in your inbox gradually, not all at once. Don't promise your team that every old conversation will be searchable on day one.
What changes in the WhatsApp Business app after you connect?
A few app features are turned off or become read-only, and linked devices get unlinked. Everyday chatting, calls, catalog and your business profile carry on in the app. Here is what to warn your team about:
| Feature | After connecting |
|---|---|
| Disappearing messages | Turned off in one-to-one chats |
| View-once messages and live location | Disabled in one-to-one chats |
| Broadcast lists | You can't create new ones; existing lists become read-only |
| Group chats | Keep working in the app, but don't sync to the API |
| Linked devices | All are unlinked once you onboard; you can re-link supported ones. WhatsApp for Windows and WearOS aren't supported |
| Calls, catalog, quick replies, labels, business profile | No change in the app |
If a customer uses an unsupported linked device to message you, the message won't reach your API inbox, so ask the team to check the phone app when something looks missing.
What are the limits, and how does billing work with Coexistence?
The number is capped at 20 messages a second, app messages stay free, and API messages are charged per delivered message. Those are the three facts that affect planning.
- Throughput: numbers used on both the app and the API have a fixed 20 messages per second, which is plenty for most teams but matters for very large campaigns.
- Cost: messages your team sends from the Business app remain free. Messages sent through the API follow Meta's per-message pricing. See our Pakistan pricing guide for current rates.
- The 24-hour window: it only applies to messages sent through the API. If a customer wrote to you just before you onboarded, no API window exists yet, so your first API reply has to be an approved template. Replies from the app aren't affected.
- Keep using the phone app: Meta can disconnect the number if the primary phone is inactive for roughly 14 days, so open the Business app regularly.
Which mistakes should you avoid?
- Deleting the old account first. If continuity matters, never start with the destructive route.
- Mixing up "same number" with "same history". Keeping a number and importing old chats are separate questions.
- Testing only outbound. Test inbound messages, replies, webhooks, CRM records and agent assignment too.
- Forgetting the app changes. Tell your team about broadcast lists, disappearing messages and linked devices before launch day.
- Switching everything at once. Keep the old process available until the inbox, automation and routing have passed a real test.
Does your country matter for Coexistence?
The steps are the same everywhere, but eligibility can depend on the number and account. The onboarding flow shows whether the existing-number option is offered, so don't delete anything until you've seen it.
- Pakistan: your number is probably already on packaging, invoices and your website, so continuity matters most. See WhatsApp API in Pakistan for local setup and PKR billing.
- UAE and Dubai: property teams often have one number tied to years of enquiries. Keep it, then add lead routing and follow-up around it, as in our Dubai real estate WhatsApp playbook.
- Elsewhere: Meta's rules on messaging and consent still apply after you connect. The API isn't a consent exemption.
How does On Cloud API help with the migration?
On Cloud API is a Meta Verified Tech Provider, so we onboard existing WhatsApp Business app numbers through Embedded Signup with Coexistence support. Once connected, your team gets a shared inbox, chatbots, AI replies and CRM connections around the number. We charge 0% markup on Meta's message rates, with plans from PKR 2,849 a month, payable in PKR by JazzCash, Easypaisa, Raast or bank transfer.
When several agents will share the number, read how a WhatsApp multi-agent inbox works.
Keep your number. Add the API.
Connect your existing WhatsApp Business number and keep the app running while your team gets automation.
Explore WhatsApp Cloud API →Frequently asked questions
Can I use my existing WhatsApp Business number with the Cloud API?
Yes. With WhatsApp Coexistence, the number you already use in the WhatsApp Business app connects to the Cloud API and stays active in the app. You onboard through a Meta partner such as a Tech Provider, using Embedded Signup.
Will I lose my chats when I connect the API?
No. Your chats stay in the Business app. If you approve sharing during setup, up to six months of one-to-one history and your contacts can also sync to your new inbox. Group chats don't sync, and media is limited to recent messages.
Do I need a new WhatsApp number?
No. Coexistence is built for businesses that want to keep the number customers already know. You only need a new number if you choose a fresh API setup, or the number is on the regular WhatsApp app instead of the Business app.
Can I still use the WhatsApp Business app after connecting the API?
Yes. With Coexistence, your team can keep sending one-to-one messages from the app while software and automation use the API on the same number. Meta keeps the messages in sync between both.
Is Coexistence the same as a full migration?
No. Coexistence keeps the Business app working on the number while adding the API. An API-only migration moves the number to run entirely through software, and you shouldn't assume old app chats come with it.
Which WhatsApp Business app version do I need?
Meta's documentation says the business must use WhatsApp Business app version 2.24.17 or higher. Update the app before you start, and onboard through a Solution Partner or Tech Provider using Embedded Signup.
What stops working in the app after I connect?
Disappearing messages, view-once messages and live location are turned off in one-to-one chats, and broadcast lists become read-only. Linked devices are unlinked, and you can re-link supported ones. Chats, calls, catalog and your business profile keep working.
Do messages cost more with Coexistence?
Messages you send from the Business app remain free. Messages sent through the API are charged per delivered message under Meta's pricing, by category and the recipient's country. Your provider's platform fee is separate.
Is there a messaging limit on a Coexistence number?
Yes. A number used on both the Business app and the Cloud API has a fixed throughput of 20 messages per second. That is enough for most teams, but very large campaigns should be planned around it.
Can a Dubai real estate business keep its existing WhatsApp number?
Yes, if the number is offered the existing-number option during onboarding. Property teams can keep the number clients already know, then add shared inbox, lead routing and CRM workflows around it.
Coexistence rules, supported features and history sync can change. Confirm the current details in Meta's documentation on onboarding WhatsApp Business app users before you disconnect anything. Not legal advice.
