Coexistence#

Coexistence lets one number work in two places: people keep chatting from the WhatsApp Business app, and your code sends and receives through the Cloud API via kenari. You don't need to migrate the number or cut over on a set date.

When you connect a number this way, Meta can sync the app's contacts and up to 180 days of chat history to your webhook once. kenari forwards that history to your endpoint and doesn't keep a copy.

Before you start#

Connect at least one other number first. Webhook endpoints can only be created on an account with at least one connected number (409 no_numbers), and the pre-flight check below needs an endpoint.
Create an enabled webhook endpoint that subscribes to both of these fields:
- history: the one-time chat history sync
- smb_message_echoes: messages you send from the WhatsApp Business app
Also subscribe to smb_app_state_sync if you want the contacts sync, and to messages for inbound messages and statuses. See Webhooks.
Have the phone with the WhatsApp Business app for that number at hand.

Step 1: run the pre-flight check#

Choose Connect a number → Keep using the WhatsApp Business app, then Run pre-flight check.

The check exists because the history sync happens only once. kenari makes sure your endpoint can receive events before Meta starts sending them.

It works like this:

kenari looks for an enabled endpoint whose fields include both history and smb_message_echoes. If there isn't one, the check fails with 409 preflight_no_endpoint.
kenari sends that endpoint a signed test event: the same synthetic messages payload as Send test, with "kenari_test": true, signed with your endpoint's secret.
Your endpoint must answer with a 2xx status within 10 seconds. If it doesn't, the check fails with 409 preflight_failed, and the response shows the status code or error kenari got.

Result	What to do
`preflight_no_endpoint`	Create or enable an endpoint on Webhooks that includes `history` and `smb_message_echoes`.
`preflight_failed`	Check that the endpoint is reachable, verifies the signature with the current secret and returns `2xx` quickly.
Success	The dashboard shows the status code and latency and unlocks step 2.

The pre-flight event is sent once, straight to your endpoint. It isn't retried and doesn't appear under Deliveries. Its webhook-id has the form msg_<uuid>, not a delivery id, so don't rely on a particular webhook-id format.

Step 2: link the app with Meta#

Once the pre-flight check passes, Link the app with Meta becomes available. It opens Meta's Embedded Signup in its coexistence mode (featureType: "whatsapp_business_app_onboarding"). Follow Meta's prompts to link the number from your WhatsApp Business app.

What happens after you connect#

The number shows a coexistence badge and the message History sync window closes … with the deadline, which is 24 hours after connecting.
kenari asks Meta to start syncing: first the WhatsApp Business app's contacts (smb_app_state_sync), then chat history (history). The resulting events reach your endpoint like any other webhook.
Messages you send from the WhatsApp Business app arrive on your endpoint as smb_message_echoes events.
About 6 hours before the deadline, kenari notifies the account if the sync isn't finished. If the deadline passes, kenari marks the sync as missed and notifies the account again.

Your history data#

kenari forwards history events to your endpoint and deletes the payload as soon as the delivery succeeds or is parked. Only the delivery record (status, attempts, timing) stays until your retention window ends.
So a history delivery can't be replayed once it's done (410 payload_expired). Make sure your endpoint stores what it receives.
history deliveries retry on the normal retry schedule while they're pending.

Limitations#

Area	Coexistence numbers
Sending rate through kenari	Fixed at 20 messages per second per number, whatever Meta's throughput tier says. See Throughput & quality.
History sync	One-shot, requested right after connecting; the window closes 24 hours after connecting.
History payloads	Not stored after delivery, so they can't be replayed.
Onboarding	Requires Embedded Signup (internal accounts only for now) and a passing pre-flight check.
Webhook signature	Meta signs these events with kenari's app secret, so verify `webhook-signature`. You can't check `X-Meta-Signature-256` yourself.

Disconnecting a coexistence number works the same way as for any other number. See Disconnecting.