Coexistence

Normally, connecting a number to the Cloud API switches off the WhatsApp Business app on that device. Coexistence is the mode where both work together: the team keeps answering from the phone while the API operates on the same number.

When it makes sense

It makes sense when the operation already runs in the app and you want to automate part of it without migrating everything at once — automated sends through the API, human support on the phone.

It doesn't when nobody will use the phone anymore. Dedicated mode is simpler and has none of the limitations below.

How to connect

In the dashboard, under Connect number, choose Coexistence. The flow is the same Meta Embedded Signup, with two extra prompts on the owner's phone:

1. Authorize the integration.
2. Authorize sharing conversation history and contacts.

The second step is optional for the customer and final for you: if they decline, there is no way to ask again without redoing the whole onboarding.

What changes day to day

	Dedicated mode	Coexistence
WhatsApp Business app	disabled	keeps working
Messages sent from the phone	—	reach you as smb_message_echoes
Incoming messages	messages webhook	messages webhook, on both sides
Previous history	doesn't exist	syncable in the first 24h
Device contacts	don't exist	syncable in the first 24h

Echoes of phone messages

Everything the team types in the app reaches you through the smb_message_echoes event, in the same shape as messages.

Subscribe to it if your system keeps the full conversation — without it you only see what the customer writes and what the API sends, and the history has holes.

{
  "field": "smb_message_echoes",
  "value": {
    "message_echoes": [
      {
        "from": "5541987111527",
        "to": "5541999999999",
        "id": "wamid.HBgN...",
        "type": "text",
        "text": { "body": "Sure, let me check that for you!" }
      }
    ]
  }
}

Contact changes

Adding, renaming or removing a contact on the phone produces an smb_app_state_sync event. That keeps happening indefinitely, not just during the initial sync.

Limitations

The 24-hour window still applies. A reply sent from the phone opens the window for the API too — both share the same conversation.

Groups don't go through the API. The app keeps accessing groups; the Cloud API doesn't see them. Group messages produce no webhook.

Calls stay in the app. Voice and video calls are not exposed by the API.

There is only one quality rating. A poorly received bulk send through the API drags down the quality that human support relies on too.

Syncing history

The most delicate step, and the least forgiving: you get 24 hours and one attempt. It's covered in Sync history.

Backing out

Disconnecting the number in the dashboard hands the whole operation back to the app. The history that was on the phone never left it.

The reverse — moving from coexistence to dedicated mode — requires redoing onboarding and switches off the app on that device.