For years, putting a WhatsApp number on the Business API meant taking it off the WhatsApp Business app. The chats on the owner’s phone stayed behind, the team lost the app they knew, and many businesses decided the API was not worth it. Coexistence changes that. One number can now run in the WhatsApp Business app and on Meta’s Cloud API at the same time: the owner keeps replying from the phone, a CRM or chatbot answers through the API, and every message shows in both. This guide covers what it needs, what comes across from the phone, what changes, what it costs, and five problems we hit building it into a production WhatsApp CRM.
What Coexistence Actually Is
Meta’s documentation calls it onboarding WhatsApp Business app users; most of the industry calls it coexistence. A business that already uses the WhatsApp Business app connects its number to a Cloud API integration through Meta’s Embedded Signup, and Meta converts the account so that the app and the API can both send and receive on the same number.
Messages flow both ways. A customer’s message arrives on the phone and at the API. A reply sent from the phone is reported to the API as an echo (the smb_message_echoes webhook), so the CRM sees the whole conversation, not only the half it sent itself.
This answers the objection we hear most often about the WhatsApp Business API: “I don’t want to give up the number my customers already have, or the chats on my phone.” With coexistence, a business keeps both.
What You Need Before You Start
| Requirement | What it means in practice |
|---|---|
| WhatsApp Business app 2.24.17 or later | The number must already be active in the WhatsApp Business app (not personal WhatsApp), on a current version. |
| A Solution Partner or Tech Provider | Coexistence is switched on through Meta’s Embedded Signup, which is offered by approved Solution Partners and Tech Providers building on the Cloud API. |
| Embedded Signup version 4 or later | Meta deprecated versions 2 and 3 on 15 October 2026. Version 4 has to ask for the coexistence flow explicitly; in version 5 it is on by default. |
| A phone that stays in use | Meta disconnects the number if the phone running the app is inactive for about 14 days. |
What Comes Across From the Phone
During onboarding the owner is asked, on the phone, whether to share their chat history. If they agree, the API side can import:
- Contacts: the address book from the WhatsApp Business app, synced once.
- Chat history: one-to-one chats from the last six months (180 days), delivered in three phases — the most recent day, then days 1 to 90, then days 90 to 180.
- Attachments: photos, documents and voice notes can be fetched only for messages from the 14 days before onboarding.
- Groups: not synced. Group chats stay on the phone only.
Both syncs must be requested within 24 hours of onboarding, and each can be requested only once. Miss the window or waste the request and the only way back is for the business to disconnect and onboard again. Lesson 1 below explains why this catches integrations out.
What Changes on the Phone, and What Does Not
Most descriptions flatten this into one list of things that “do not work”, which makes coexistence sound worse than it is in one way and better than it is in another. There are two separate lists.
| Still works on the phone, but not through the API | Turned off on the phone after connecting |
|---|---|
| Group chats | Disappearing messages |
| Voice and video calls | View-once messages |
| Catalog, orders and Status | Live location sharing |
| Marketing messages, quick replies, labels, greeting and away messages | Broadcast lists (existing lists become read-only) |
| Business profile and Channels | — |
The left column is a smaller loss than it sounds: the owner keeps those features, and the CRM simply never sees them. The right column is a real change to how the owner uses WhatsApp, and it is the one to explain before connecting, not three weeks after.
- Linked devices are unlinked when the number connects. Supported ones can be linked again afterwards, up to WhatsApp’s usual limit of four.
- WhatsApp for Windows and WearOS are not supported on a coexistence number.
- Sending through the API is fixed at 20 messages per second. A campaign to 10,000 contacts takes at least eight minutes and twenty seconds, and the sending code has to pace itself to that limit.
What It Costs
Messages sent from the WhatsApp Business app stay free, exactly as before. Messages sent through the API are billed at Meta’s normal Cloud API rates, which have been charged per message since 1 July 2025: by category (such as marketing, utility, authentication and service) and by the recipient’s country, and only when the message is delivered. Messages customers send to the business are free.
Two changes that took effect on 1 October 2026 matter for a coexistence setup:
- Each number gets 1,000 free service messages a month — free-form replies inside the 24-hour customer service window. Service messages beyond that are charged, and unused messages do not roll over.
- Utility templates sent inside the 24-hour window are no longer free.
One more rule is specific to coexistence: messages sent from the phone do not open or extend the 24-hour customer service window. Only a message from the customer does. If the owner has been chatting from the phone and the CRM then tries to send a free-form reply, Meta can still refuse it, because the window closed 24 hours after the customer last wrote.
Five Things We Learned Building It
We built coexistence into Pingly, our own WhatsApp CRM, and connected it to production numbers in September 2026. Each point below is a failure we saw in production, and none of them is obvious from the documentation.
1. Chat history never arrives unless you ask for it
After connecting, everything looked right: the number showed as on the Business app, its status was connected and the webhooks were subscribed. We onboarded the same number four times and received no history at all. Meta does not send it unprompted. You request it with two calls to the number’s smb_app_data endpoint — sync_type smb_app_state_sync for contacts, then history for messages — inside the 24-hour window. Each is a single shot, so record that you have asked only once Meta accepts the request, and clear that record if Meta refuses it, so a passing error does not cost the business a full re-onboarding.
2. Webhooks arrive before your system is ready for them
In production, three events for a newly connected business arrived 11 seconds before our system had finished saving the account, and were dropped. Meta retries a webhook only when it receives an error, and a webhook endpoint should answer quickly with success, so an event that cannot yet be matched to an account is not delayed — it is lost. History is delivered in exactly that gap. Hold unmatched events for a short time and replay them once the account is stored.
3. A reply from the owner’s phone must silence the bot
This is the whole point of coexistence, and it is easy to get wrong. When the owner replied from their phone, our echo handling dealt with that one message correctly but did not mark the conversation as taken over, so the customer’s next message got an AI answer in the middle of a live human conversation. An echo should hand the chat to the person until someone hands it back. Imported history must not do the same, or six months of old chats would switch the bot off everywhere at once.
4. The owner’s messages do not open the 24-hour window
Our inbox counted every message as activity, including echoes from the phone, so it showed conversations as open and let staff send free-form replies that Meta then refused. Three replies failed before we found it. Only a genuine customer message should start the window, and when Meta refuses a send, show the reason it gives rather than just a failed tick.
5. Measure the 24-hour import, or a stall looks like a quiet one
An import that never starts looks exactly like one that is still running, and one that stops halfway can sit unnoticed indefinitely. Record when the window opened and how far the import has got, and tell the business when 24 hours pass without it finishing — including the honest news that messaging is unaffected and only a fresh onboarding can bring the history across.
Disconnecting, and Being Disconnected
The business disconnects from the phone, in the WhatsApp Business app under Settings > Account > Business Platform > Disconnect Account. Meta’s Deregister API cannot be used on a coexistence number.
Meta can also disconnect it. If the phone running the app is inactive for about 14 days, the integration receives an account_update webhook with the event PARTNER_REMOVED. Handle it: stop sending from that number, tell the business, and explain how to onboard again, rather than letting messages fail one at a time.
Is Coexistence Right for Your Business?
- Yes, if the owner or a few staff already handle customers from the WhatsApp Business app and you want a CRM, a chatbot or automated notifications without changing number.
- Yes, if customers know your number from shop boards, invoices and ads, and changing it would cost you enquiries.
- Think twice if you rely on broadcast lists or disappearing messages on the phone. Both are switched off.
- Use a standard API number instead if you need to send faster than 20 messages per second, or if nobody will keep the phone in use.
Frequently Asked Questions
Can I use the WhatsApp Business app and the WhatsApp Business API on the same number?
Yes. Meta’s coexistence onboarding connects a number that is already in the WhatsApp Business app (version 2.24.17 or later) to the Cloud API without removing it from the app. Both can then send and receive on that number.
Will I lose my chats when I connect to the API?
No. Your chats stay on your phone. If you agree during onboarding, the last six months of one-to-one chats can also be copied to the API side, provided the copy is requested within 24 hours of connecting. Group chats are not copied.
Are messages I send from the WhatsApp Business app charged?
No. Messages sent from the app remain free. Only messages sent through the API are billed, at Meta’s standard per-message Cloud API rates.
Can I still send broadcasts?
Not from the phone: broadcast lists are switched off and existing lists become read-only. Broadcasts move to the API as approved template messages, sent at up to 20 a second and billed per message.
What happens if I stop using the phone?
If the phone running the WhatsApp Business app is inactive for about 14 days, Meta disconnects the number from the API and your integration is notified. Reconnecting it to the API means going through onboarding again.
Coexistence removes the main reason businesses hesitated over the WhatsApp Business API: they no longer have to give up their number or their phone. Connecting is the easy part. The work is in what follows — requesting the history in time, catching events that arrive early, handing chats cleanly between the bot and the owner, and pacing campaigns to 20 messages a second. Samcom builds WhatsApp Business API integrations, including coexistence, chatbots and CRM connections. Tell us about your setup and we will tell you whether coexistence fits it.