What the platform does for you
- Resume on restart. After a deploy or crash, every paired session is reconnected automatically within seconds. You do not call
/startagain. - Heartbeat. Every two minutes each session is checked; dropped connections are re-established with backoff.
- Routing. Requests are forwarded to the machine holding the session; if that machine is momentarily unavailable you receive a
502and can retry. - Persistence. Webhook settings, workspace id, group opt-in and per-session secrets survive restarts.
- Alerting. Repeated reconnect failures and terminal states page our operators.
Terminal states
Some conditions can only be resolved by a person and are left alone (with an alert):
| State | Cause | Fix |
|---|---|---|
logged_out | The device was removed under Linked devices, or WhatsApp expired it. | POST /start → new QR → user re-scans. |
replaced | The same session was opened elsewhere (stream replaced). | Stop the other client; POST /start. |
banned | WhatsApp temporarily or permanently banned the number. | Wait out a temporary ban; see fair use. Nothing the API can do. |
outdated | WhatsApp requires a newer client version. | We deploy an update; sessions resume automatically. |
Monitoring your sessions
Poll GET /health/clients (no auth) for a dashboard, or POST /check-state per session before sending in bulk:
GET https://api.meowsapp.com/health/clients
{ "failedCount": 1, "clients": [ { "clientId": "acmemain", "status": "connected", "connected": true, "loggedIn": true, "reconnects": 2, "lastDisconnect": "" }, { "clientId": "acme2", "status": "logged_out", "connected": false, "loggedIn": false, "lastDisconnect": "device removed" } ] }Alert on status, not on connected
A session may show connected: false for a few seconds during a routine reconnect. Alert when status is a terminal state, or when connected stays false for more than five minutes.
Retrying safely
502on a send means nothing was delivered — retry with exponential backoff (1 s, 2 s, 4 s…, cap at a minute). Sends are not idempotent; keep your own retry limit.200with awarningmeans delivered; do not resend.- Webhook retries are on our side (4 attempts). De-duplicate on
(clientId, chatRoomId, messageId).