Stay connected - WABridges

Two kinds of disconnect

A disconnected event does not always mean trouble, and the difference is one field.

No reason means a transient drop - a network blip, a WhatsApp server moving you. The bridge reconnects by itself and you will get connected shortly after. Log it, do not page anyone.

A reason means the session is terminal and will not come back on its own. logged_out means the device was unpaired, usually from the phone's Linked devices screen, and someone has to pair it again. stream_replaced means another client took over the session.

transient - it will heal

{"event": "disconnected"}

terminal - needs a person

{
  "event": "disconnected",
  "reason": "logged_out",
  "detail": "401: logged out"
}

Alert on a disconnected event that carries a reason. Alerting on every disconnected event will page you for ordinary network weather.

Coming back up

connected fires when the link is live again and carries the number, which is worth asserting against the number you expect if you run many bridges.

POST https://yourbackend.com/hook

{
  "event": "connected",
  "phone": "15550001234"
}

The catch-up flood

After a reconnect, WhatsApp replays everything that happened while the bridge was away, and this is where naive integrations embarrass themselves - a bot that answers every message will answer two hours of backlog at once.

You are warned first. offline_sync_preview arrives with a count of what is about to be replayed. Every event delivered during that window carries "offline": true. offline_sync_completed closes it, and events after that are live again.

So the rule is simple: skip auto-replies for any event carrying offline: true. Store them, count them, summarise them - just do not answer each one as if it arrived now.

POST https://yourbackend.com/hook

{
  "event": "offline_sync_preview",
  "total": 142,
  "messages": 120,
  "receipts": 14,
  "notifications": 8,
  "app_data_changes": 0
}

then, when it is done

{
  "event": "offline_sync_completed",
  "count": 142
}

Checking without waiting to be told

Webhooks are the fast path, but a health check should not depend on having received one. Poll the bridge instead - status is connected, disconnected or unpaired.

Once a minute per bridge is plenty and sits far inside the 120 per minute budget. Treat unpaired as a distinct alert from disconnected: it means nobody ever linked a phone, which is a setup problem rather than an outage.

curl

curl https://wabridges.com/api/instances/user-123/proxy/status \
  -H "Authorization: Bearer $WA_API_KEY"

While a bridge is down, sends return 503 with Retry-After rather than being silently dropped, and messages people send still arrive on the phone as normal - the bridge is a linked device, not the account.