# "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.

Canonical: https://docs.whabuzz.com/guides/coexistence/

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 {#connect}

You need a number that is already registered in the WhatsApp Business app, and the phone with the app on it.

1. In the console, open **Numbers** and choose **Connect a Business app number**. Read the summary and continue to Meta.
2. 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.
3. 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.
4. 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`](https://docs.whabuzz.com/reference.md#tag/numbers/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 {#events}

Subscribe an endpoint to the events below, or to `*`. All use the normal [envelope](https://docs.whabuzz.com/events.md#envelope).

| Event | When |
|---|---|
| [`message.echo`](https://docs.whabuzz.com/events/message-echo.md) | The business sent a message from the Business app. Outbound (`direction: out`); `wa_id` is the recipient. |
| [`contact.synced`](https://docs.whabuzz.com/events/contact-synced.md) | A contact was added or removed in the Business app, including the one-time copy of existing contacts. One event per contact. |
| [`history.completed`](https://docs.whabuzz.com/events/whabuzz-events.md#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](#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 {#history}

- **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.synced` events.
- **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}`](https://docs.whabuzz.com/reference.md#tag/media/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.completed` once. 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`](https://docs.whabuzz.com/reference.md#tag/events/GET/v1/events), or fetch one with [`GET /v1/events/{event_id}`](https://docs.whabuzz.com/reference.md#tag/events/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](https://docs.whabuzz.com/guides/retention.md) window like any other event.

## What is not forwarded {#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](https://docs.whabuzz.com/stream.md), even for a `*` subscription. They are queryable only, as above. Subscribing to them is rejected.

## Limits {#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 {#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 {#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](https://docs.whabuzz.com/pricing.md).