"Coexistence: keep the WhatsApp Business app"
Use one number in the WhatsApp Business app and through WhaBuzz at the same time; onboarding, echoes, contact and history sync, limits.
Coexistence lets one phone number work in two places at once: in the WhatsApp Business app on the owner's phone, and through WhaBuzz and the Cloud API. Staff keep answering from the app. Your software sends and receives through the API. Messages from both sides land in the same chat for the customer.
This is Meta's WhatsApp Business app coexistence feature. WhaBuzz connects the number and passes Meta's data through; it adds no rules of its own.
#Connect
You need a number that is already registered in the WhatsApp Business app, and the phone with the app on it.
- In the console, open Numbers and choose Connect a Business app number. Read the summary and continue to Meta.
- In the Meta window, sign in, pick the business and the WhatsApp account, and choose the number that is on the Business app. Meta shows a QR code; scan it from the app on the phone.
- Meta asks whether to share your contacts and your chat history with the connected platform. Choose what you are happy to share. If you decline history, no history is imported.
- When the window closes, WhaBuzz connects the number. It does not register it (the number stays on the app, so there is no PIN) and it asks Meta once for the contacts copy and once for the history copy.
The number then appears in the console with a Coexistence label, and the same fields are on GET /v1/numbers: coexistence, is_on_biz_app and coexistence_sync (when each copy was requested, the contacts count, and the history phase, progress and result). If Meta refuses a request, the sync object carries Meta's error in its own words, and the console offers Request sync again.
Meta only answers a sync request within 24 hours of connecting. After that, the request fails with Meta's error and WhaBuzz cannot import the copy later.
#Events you receive
Subscribe an endpoint to the events below, or to *. All use the normal envelope.
| Event | When |
|---|---|
message.echo | The business sent a message from the Business app. Outbound (direction: out); wa_id is the recipient. |
contact.synced | A contact was added or removed in the Business app, including the one-time copy of existing contacts. One event per contact. |
history.completed | The history import finished, or the business declined it. Raised once per number. |
number.connection | The number's connection changed, for example partner_removed. See Disconnect. |
An echo is not a customer message. It never produces message.inbound. Messages you send through the API are message.outbound, as before.
#What syncs and when
- Contacts. Meta sends the existing contacts once after you connect, then each add or remove as it happens in the app. They arrive as
contact.syncedevents. - History. Meta sends past chats in chunks, each with a phase and a progress value. Meta provides up to 180 days of history. Media is available only for the last 14 days; older messages arrive without their files, and media that arrives later is fetched on demand through
GET /v1/media/{media_id}. Group chats are not included. - When it ends. When Meta reports 100% progress, or the business declined history, WhaBuzz raises
history.completedonce. Chunks that arrive later are still stored and de-duplicated.
History never overwrites a newer message. A history message that WhaBuzz already has (from live traffic or an earlier chunk) is skipped.
#Reading imported history
History is stored but not delivered. After history.completed, page through it with GET /v1/events?type=message.history, or fetch one with GET /v1/events/{event_id}. Each message event carries the thread (wa_id), Meta's message object, and a direction (in or out) worked out from the sender. History events expire with your retention window like any other event.
#What is not forwarded
message.history (one per imported message) and history.chunk (one per Meta batch, holding the raw body once) are never sent to webhook endpoints and never appear on the stream, even for a * subscription. They are queryable only, as above. Subscribing to them is rejected.
#Limits
- 20 messages per second on the number, a Meta limit for coexistence numbers. WhaBuzz caps its own queue at 20 per second for these numbers. Meta's own answer (
130429) is returned unchanged if a direct send exceeds it. - Open the app every 14 days. The Business app on the primary phone must stay active; if it is not opened for 14 days, Meta disconnects the number.
- No groups. Group chats are not available through the API.
- No deregister. The API cannot deregister a coexistence number. Disconnect it from the Business app.
- Profile edits happen in the app. Name, photo and about cannot be changed through the API for these numbers.
- History window. 180 days, media for the last 14 days only, no group history.
#Disconnect
To stop, the business disconnects WhaBuzz in the Business app (Settings, Account, Business platform). Meta tells WhaBuzz, and the number becomes disconnected with connection_detail: "partner_removed"; a number.connection event is raised, and sends answer 409 number_not_connected. Connect the number again to resume. The messages and events already stored stay until your retention window removes them.
#Billing
A coexistence number is billed like any other connected number: the flat monthly fee per number, and Meta's rates paid to Meta. See Pricing.
This page as Markdown: /guides/coexistence.md. All docs in one file: /llms-full.txt. Status.