WhatsApp Coexistence: Business App and Cloud API Together
For years the deal was blunt: if you wanted your WhatsApp Business app number on the official API, you deleted the app account, lost your chat history and moved over. Plenty of small businesses refused, because the app on the owner's phone is where the relationships live.
WhatsApp coexistence is Meta's answer. It lets a number keep running in the WhatsApp Business app while also being connected to the Cloud API through a partner, with messages mirrored between the two. It is genuinely useful, but it is not "the app plus everything the API does". Several app features switch off, throughput is capped, the phone has to stay in use, and the setup has a 24-hour clock on it. This guide walks through each part, from Meta's current documentation.
How coexistence onboarding works
Coexistence is a variant of Embedded Signup, so you get it through a partner: a Solution Partner or Tech Provider whose product supports WhatsApp Business app onboarding. Direct developers who are not partners can't set it up for their own number.
- In the partner's product, you click to connect WhatsApp and sign in with Facebook.
- You enter your Business app number. On Embedded Signup v4 and later the flow detects that the number is on the app and switches to coexistence by itself.
- You confirm the profile WhatsApp shows (name, picture, category, website) and pick or create a business portfolio.
- On your phone, inside the WhatsApp Business app, you scan a QR code (Meta also sends a WhatsApp message with a link to it), or follow the in-app prompt to Connect to the Business Platform.
- The app asks whether to share your chat history with the partner. You can decline.
- You accept the terms and finish.
Behind the scenes Meta converts your existing WhatsApp Business account into a Messaging account with the same ID and shares it, plus the WhatsApp account that holds your number, with the partner. The number is already registered, so there is no deletion and no registration step.
Requirements: WhatsApp Business app version 2.24.17 or newer, and a partner with session logging and working webhooks. Availability has varied by country during the rollout, so confirm with your provider that your market is supported before you plan around it.
What syncs, and what changes in the app
Meta publishes a feature comparison. The short version: one-to-one chats and contacts come across; most of the app's power features either stay app-only or switch off.
| Feature | In the Business app after onboarding | Available through the API |
|---|---|---|
| One-to-one chats | Work as before; edit and delete for everyone now supported | Yes, mirrored both ways; last 6 months can be synced |
| Contacts | No change | Yes, contacts with a WhatsApp number sync |
| Group chats | No change | No, groups are not synced |
| Disappearing messages | Turned off for one-to-one chats | No |
| View once messages | Disabled for one-to-one chats | No |
| Live location | Disabled for one-to-one chats | No |
| Broadcast lists | Disabled; existing lists become read-only | No |
| Voice and video calls | No change | No |
| Catalog, orders, status | No change | No |
| Greeting and away messages, quick replies, labels | No change | No |
| Business profile and channels | No change | No |
The broadcast list change catches people out. If your weekly offer goes out through a broadcast list in the app, that stops; you would send it through the partner as a marketing template instead, at Meta's per-message rate.
Limits you will actually hit
- Throughput is fixed at 20 messages per second. Meta sets this to keep the number compatible with the app. A normal Cloud API number starts at 80 per second. Our guide to WhatsApp API throughput explains what that means for bulk sends.
- Linked devices get unlinked at onboarding. You can link companions again afterwards, except WhatsApp for Windows and WhatsApp for WearOS, which Meta lists as unsupported. Messages from users on unsupported companions do not trigger webhooks, and you may see error
131060for them. - The phone has to stay in use. Meta's disconnection reasons include
PRIMARY_INACTIVITY(primary device inactive for about 14 days) andCOMPANION_INACTIVITY(about 30 days). Open the app on the main phone at least every couple of weeks. - History sync is a one-shot, 24-hour job. After onboarding, the partner has 24 hours to start syncing contacts and history. Each sync can run once; redoing it means offboarding and onboarding again. Keep the app open while it runs.
- History has a horizon. Synced history covers messages from up to 180 days before onboarding, delivered in phases (day 0 to 1, day 1 to 90, day 90 to 180). Media files are only included for roughly the last 14 days.
If you are the developer at the partner, the sync is two calls to the same endpoint, contacts first:
curl -X POST "https://graph.facebook.com/v23.0/PHONE_NUMBER_ID/smb_app_data" \
-H "Authorization: Bearer $WHATSAPP_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "messaging_product": "whatsapp", "sync_type": "smb_app_state_sync" }'
curl -X POST "https://graph.facebook.com/v23.0/PHONE_NUMBER_ID/smb_app_data" \
-H "Authorization: Bearer $WHATSAPP_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "messaging_product": "whatsapp", "sync_type": "history" }'
Subscribe to the history, smb_app_state_sync, smb_message_echoes and account_update webhook fields first. Messages the owner types in the app arrive as smb_message_echoes, and you must show them in the thread or your inbox will have holes. To confirm a number is in coexistence mode, request fields=is_on_biz_app,platform_type on the phone number ID; you want true and CLOUD_API. Use the current Graph API version from Meta's changelog.
How billing works in coexistence
The pricing rule is simple once you see it: the app stays free, the API is billed.
- Messages you send from the WhatsApp Business app remain free.
- Messages sent through the Cloud API follow Meta's per-message pricing by category and recipient country, including the 1,000 free service messages per number per month from October 1, 2026. Our WhatsApp API pricing guide has the detail.
- The 24-hour customer service window only applies to API sends. Replies from the app do not open, extend or affect API windows.
- A window opens only when a customer messages you after onboarding. If someone wrote just before you connected, the API can only answer them with a template.
That last point produces a common support ticket on day one: "the API won't let me reply to a customer who just messaged". Reply from the app, or wait for their next message.
Disconnecting and device changes
You can't deregister a coexistence number through the API. To leave, the business opens the WhatsApp Business app and goes to Settings > Account > Business Platform > Disconnect Account. The partner receives an account_update webhook with a PARTNER_REMOVED event, which can include the reason and who started it.
Changing phones or reinstalling the app offboards the API connection automatically. When the owner finishes registering on the new device, WhatsApp shows the previously connected products with a pre-checked opt-in, and reconnection usually completes within minutes. Partners get ACCOUNT_OFFBOARDED and then ACCOUNT_RECONNECTED; Cloud API sending is suspended in between, so queue messages rather than failing them.
Coexistence or a linked-device workspace?
Both keep the app on the phone. They solve different problems.
| Coexistence | Linked-device workspace | |
|---|---|---|
| Part of Meta's official platform | Yes | No |
| Templates, buttons, green tick path | Yes | No |
| Groups in the team tool | No | Yes |
| Per-message charges | On API sends | None; flat subscription |
| Broadcast lists in the app | Disabled | Unchanged |
| Works with personal WhatsApp | No, Business app only | Yes |
| Best for | Adding automated notifications and bots to a Business app number | A team replying together, including in groups |
Where Tenashi fits
Coexistence suits a business that wants template notifications or a chatbot on its existing app number and is happy to keep group work on the owner's phone. If your goal is for a team to share the number, including the groups it is already in, Tenashi takes the linked-device route instead. You link your WhatsApp or WhatsApp Business number with a QR scan, your history imports, and everyone works one inbox with DMs and groups, a CRM under each chat, assignments and notes, from $18/mo. Nothing in the app gets switched off.
The limit: Tenashi is not Meta's platform, so there are no templates, interactive messages or green tick, sends are paced to protect the number, and ban protection reduces risk rather than removing it. For the overall map, start with the complete guide to the WhatsApp API, and if you are weighing a full move instead, read how to migrate a WhatsApp number to the API.
See every feature · Get started
FAQ
Is WhatsApp coexistence free?
Coexistence onboarding has no Meta fee, and messages you send from the WhatsApp Business app stay free. Messages sent through the Cloud API are charged per delivered message by category and the recipient's country, as on any API number. Your partner will usually charge its own subscription or fees on top, so check their pricing before connecting.
Can I keep using WhatsApp groups with coexistence?
Yes, in the app. Coexistence does not change group chats on your phone, but groups are not synced to the Cloud API, so your partner's tool can't read or reply to them. If your team needs to work groups from a shared tool, coexistence will not get you there; a linked-device workspace can.
Do I need a BSP for WhatsApp coexistence?
You need a partner. Coexistence runs through Embedded Signup, which only Solution Partners and Tech Providers can offer, so the product you connect must support WhatsApp Business app onboarding. A business that integrates directly without a partner can't turn coexistence on for its own number through the developer dashboard alone.
What happens if I don't open the WhatsApp Business app?
The API connection can be dropped. Meta lists primary device inactivity of about 14 days as a disconnection reason, and companion devices are dropped after about 30 days of inactivity. When that happens your partner receives a disconnection webhook and API messaging stops. Open the app on the main phone regularly.
Can I use coexistence with a personal WhatsApp number?
No. Coexistence is only for numbers on the WhatsApp Business app. A personal WhatsApp Messenger number has to be deleted before it can be registered on the Cloud API. WhatsApp does let you move a Messenger account to the Business app on the same number first, after which coexistence becomes possible.
Coexistence gives you the API without giving up the app, at the price of a few app features and some housekeeping. If what you need is the whole team on the number, groups included, see every Tenashi feature.