How to know when a customer's WhatsApp or social connection drops
easyCoexistence sends a platform signed status events when a customer's connection connects, drops, is removed or is suspended. A WhatsApp number sends connection.connected, connection.disconnected with Meta's reason, connection.removed, connection.suspended or connection.token_missing; a social account sends the channel.* equivalents, without token_missing. Each is a JSON POST signed with X-EC-Signature and retried with backoff for about 33 hours until your endpoint answers 2xx.
PRIMARY_INACTIVITY: Meta's reason when the primary device was inactive for approximately 14 days, disconnecting a Coexistence number.
COMPANION_INACTIVITY: Meta's reason when a companion device was inactive for approximately 30 days.
The webhook that reports a disconnection. Meta always sends it to the app's default callback URL, never to an override.
How often a status event is tried after any answer outside 2xx, with gaps of 1 minute to 24 hours, over about 33 hours.
Oldest signed timestamp t an endpoint should accept on a status event, comparing the HMAC in constant time.
Which status events are there?
Nine, in two families that share one endpoint and one signing secret. Numbers use connection.* and social accounts use channel.*, so a receiver written for numbers can skip channel events by name. Set the endpoint in the dashboard under Profile, then Developers, or with the MCP tool set_partner_events_url; the signing secret is shown once, when the URL is saved.
What does a connection event carry?
The delivery's id, a UUID; the event name; occurred_at in ISO 8601; and a connection object with id, external_ref, connect_session_id, phone, name, waba_id, phone_number_id, status and token_ready. Some events add a top-level field: reason on connection.disconnected and connection.suspended, detected_by set to health_check when easyCoexistence's own periodic check found the drop rather than Meta's webhook, and connect_session_id when a connect session produced the event.
{
"id": "5c2a9e70-…",
"event": "connection.disconnected",
"occurred_at": "2026-10-31T10:15:02.114Z",
"connection": {
"id": "<CONNECTION_ID>",
"external_ref": "customer_4821",
"connect_session_id": "cs_…",
"phone": "+55 11 9…",
"name": "Clínica Sorriso",
"waba_id": "<WABA_ID>",
"phone_number_id": "<PHONE_NUMBER_ID>",
"status": "disconnected",
"token_ready": true
},
"reason": "PRIMARY_INACTIVITY"
}What does a channel event carry?
The same envelope with a channel object in place of connection. It is the GET /channels/{id} view: id, channel for the network, external_ref, connect_session_id, name, username, external_id, status, token_ready, webhook_url, disconnected_reason, last_checked_at and created_at. There is no token_missing for channels, since a social sign-in always yields the customer's own token, and a channel.connected that came from a connect session carries connect_session_id at the top level too.
{
"id": "0b7e41d2-…",
"event": "channel.disconnected",
"occurred_at": "2026-10-31T10:15:02.114Z",
"channel": {
"id": "<CHANNEL_ID>",
"channel": "tiktok",
"external_ref": "customer_4821",
"connect_session_id": "cs_…",
"name": "Clínica Sorriso",
"username": "clinicasorriso",
"external_id": "<TIKTOK_OPEN_ID>",
"status": "disconnected",
"token_ready": false,
"webhook_url": "https://hooks.example.com/social",
"disconnected_reason": "<THE_NETWORK'S_MESSAGE>",
"last_checked_at": "2026-10-31T10:15:02.000Z",
"created_at": "2026-10-28T16:40:09.000Z"
}
}What do the disconnection reasons mean?
reason on connection.disconnected is the code Meta put in the disconnection_info of its account_update webhook, which Meta includes for numbers on both the WhatsApp Business app and the Cloud API. It is null when Meta gave none. The codes in Meta's reference:
PRIMARY_INACTIVITY: the phone running the WhatsApp Business app was inactive for about 14 days, the 14-day rule. A new connect session reconnects the number.ACCOUNT_DISCONNECTED: the account was disconnected through Meta's enforcement or by the customer, who may have removed access or deleted the account.COMPANION_INACTIVITY: a companion device was inactive for about 30 days.BUSINESS_DOWNGRADE: the number was registered with the consumer WhatsApp app.CHANGE_NUMBERandUSER_RE_REGISTERED: the customer changed the number, or registered it again on a new device.
Which headers come with a status event?
Five, on every attempt: Content-Type application/json, User-Agent easyCoexistence-webhooks/1, X-EC-Event with the event name, X-EC-Delivery with the same id as the body, and X-EC-Signature. The signature reads t=<unix>,v1=<hex>, where v1 is the HMAC-SHA256 of t, a dot and the raw body, keyed with your account's signing secret, which starts with whsec_. Each attempt is signed afresh, so a retry carries a new t over the same body.
import hashlib, hmac, json, os, time
SECRET = os.environ["EC_EVENTS_SECRET"].encode() # whsec_..., shown once in Profile > Developers
def verify(raw: bytes, header: str) -> bool:
parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
t, v1 = parts.get("t", ""), parts.get("v1", "")
if not t.isdigit() or abs(time.time() - int(t)) > 300:
return False # missing, or more than 5 minutes off
mac = hmac.new(SECRET, t.encode() + b"." + raw, hashlib.sha256).hexdigest()
return hmac.compare_digest(mac, v1)
def handle(raw: bytes, headers) -> int:
if not verify(raw, headers.get("X-EC-Signature", "")):
return 401
event = json.loads(raw)
if already_processed(event["id"]): # the X-EC-Delivery id, the same on every retry
return 200
enqueue(event) # act on event["event"]; the latest occurred_at wins
return 200How are failed deliveries retried?
The first attempt goes out as the event happens. An answer outside 2xx, no answer within 10 seconds, a network error or a redirect counts as a failure, and the event is tried again with growing gaps, from 1 minute to 24 hours, seven attempts in all over about 33 hours, before it is dropped. Deliveries go only to an HTTPS address that resolves to a public IP. An event that happens while no endpoint is set is never queued, and removing the endpoint stops whatever is pending.
Why handle each id once and check occurred_at?
Because a retry repeats the delivery exactly, with the same id in the body and in X-EC-Delivery, and because a retried event can arrive after a newer one. Store the ids you have processed and skip repeats. Then compare occurred_at with the last state you recorded for that connection, or read GET /connections/{id} or GET /channels/{id} before acting on an event that might be stale.
What should a platform do when a number drops?
Act on the reason. After PRIMARY_INACTIVITY, ask the customer to open the WhatsApp Business app and send them a new connect session for the same number. Reconnecting it on the same WhatsApp Business Account keeps its connection ID, puts your webhook destination back and sends connection.connected, after which you read its credentials again; connection.token_missing instead means Meta issued no token on that run. Meta sends the account_update behind a drop only to the app's own callback, never to your URL, so this event is how your platform hears of it.
What should a platform do when a social account drops?
On channel.disconnected, a new connect session with the same channel signs the account in again, under the same channel ID. channel.removed means access is gone: the token is forgotten and any webhook destination cleared, so set the destination again if the customer reconnects. A suspended number or channel comes back by reconnecting it once your subscription is active again.
Common mistakes
- Treating a retry as a new event. It carries the same id in the body and in X-EC-Delivery, so record processed ids, or one drop can alert a customer twice.
- Applying events in arrival order. A retried event can land after a newer one, so compare occurred_at, or read the connection before acting.
- Saving the events URL again to fix a typo without updating the backend. Saving issues a new signing secret, and every delivery fails verification until your endpoint uses it.
- Doing the work before answering. A handler that takes longer than 10 seconds counts as failed and the event comes back, so answer 2xx first and process afterwards.
easyCoexistence watches each customer's WhatsApp number and social accounts around the clock and sends your platform a signed event when one connects, drops, is removed or is suspended, with Meta's reason for a number that drops. US$ 9 to US$ 0.75 per connection per month, falling as you add connections, with the first 3 days free.
easyCoexistence is a multichannel API and MCP server that connects AI agents such as Claude and ChatGPT to WhatsApp, Instagram, TikTok, Facebook and more. On WhatsApp it uses Coexistence: the business keeps using its number in the WhatsApp Business app while the AI works through Meta's official API.
Frequently asked questions
What does PRIMARY_INACTIVITY mean?
It is Meta's reason for disconnecting a Coexistence number whose WhatsApp Business app went unused on its primary device for about 14 days. A new connect session for that customer reconnects the number.
Do status events include messages?
No. They cover a connection's status. A number's messages go from Meta to its own webhook destination, and social comments and DMs to each channel's destination.
Where do I set the events URL?
In the dashboard under Profile, then Developers, or with the MCP tool set_partner_events_url. The signing secret is shown once, and saving the URL again issues a new one.
Can I ignore channel events if I only handle numbers?
Yes. channel.* events have their own names and carry a channel object instead of connection, so a receiver can skip any event whose name does not start with connection.
Keep reading
Connect your first channel in two minutes.
No platform reviews to wait for. Connect WhatsApp, Instagram, TikTok or another channel, then ask your AI to post, reply or report, and watch it work.
- 3 days free
- Cancel any time
- Official APIs only
- Monitored 24/7
Verified on