Sessions

Start or resume a session

Begin QR pairing for a new clientId, or reconnect an already-paired one. Idempotent, returns immediately. Pass your webhook in the body so the session never exists without one.

curl -X POST "https://api.meowsapp.com/start?clientId=acmemain" \
  -H "Authorization: Bearer $SN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://example.com/whatsapp/incoming",
    "webhookToken": "choose-a-long-random-secret"
  }'

{
  "clientId": "acmemain",
  "status": "initializing",
  "podName": "node-1",
  "webhookUrl": "https://example.com/whatsapp/incoming",
  "pollLookupUrl": ""
}

status moves to qr (scan needed) or straight to connected if the device is already paired. podName is informational — routing is automatic.

Get the pairing QR

Poll every ~2 s after /start until status is connected. While status is qr, render the data-URL PNG for the user to scan under WhatsApp → Linked devices.

curl "https://api.meowsapp.com/qr?clientId=acmemain" -H "Authorization: Bearer $SN_TOKEN"

{ "clientId": "acmemain", "status": "qr", "qr": "data:image/png;base64,iVBORw0…" }

qr is an empty string unless status is qr. The code rotates automatically; keep polling and re-render.

Pair with a phone-number code

Alternative to the QR: returns an 8-character code the user types into WhatsApp → Linked devices → Link with phone number. Call /start first.

{ "clientId": "acmemain", "phone": "60123456789" }

{ "clientId": "acmemain", "phone": "60123456789", "code": "ABCD-EFGH" }

Check connection state

Cheap, always 200. Use it before sending in bulk or in a health dashboard.

{ "clientId": "acmemain" }

{ "status": true,  "state": "60123456789:[email protected]" }   // connected; state = own JID
{ "status": false, "state": "not connected" }
{ "status": false, "state": "unknown clientId" }

List sessions

Every clientId your token can see, with its linked number and current pod.

No parameters

{ "clients": [ { "clientId": "acmemain", "jid": "60123456789:[email protected]", "podName": "node-0", "orgId": "acme", "webhookUrl": "https://example.com/whatsapp/incoming" } ] }

Set or clear the webhook

Change where inbound events go without restarting the session. Persisted; survives reconnects and restarts. Empty webhookUrl disables delivery.

{ "clientId": "acmemain", "webhookUrl": "https://example.com/whatsapp/incoming", "webhookToken": "…" }

{ "ok": true, "clientId": "acmemain", "webhookUrl": "https://example.com/whatsapp/incoming", "pollLookupUrl": "" }

Enable hosted history (workspace id)

Attach a workspace/organisation id of your choosing. Required only if you use the hosted inbox: until it is set, no history is stored. Call once per clientId; it persists.

{ "clientId": "acmemain", "orgId": "acme" }

{ "ok": true, "clientId": "acmemain", "orgId": "acme" }

Per-session API secret

Give a third party (a customer of yours, a contractor) access to one session only. Requests naming this clientId are then accepted with either your master token or this secret.

{ "clientId": "acmemain", "secret": "k9F2…(32 random chars)" }

{ "clientId": "acmemain", "hasSecret": true }

Enable group messages

Off by default: group traffic is noisy. Turn it on to receive group messages as webhook events (isGroup: true). Persisted per session.

{ "clientId": "acmemain", "enabled": true }

{ "ok": true, "clientId": "acmemain", "enabled": true }

Unlink and delete a session

Logs the device out of WhatsApp (removes it from Linked devices) and deletes the session. The next /start with the same clientId pairs fresh.

{ "clientId": "acmemain" }

{ "ok": true, "clientId": "acmemain" }
// partial: local session removed, but WhatsApp did not confirm the logout
{ "ok": true, "clientId": "acmemain", "warning": "WhatsApp-side logout failed (…) — remove the device under Linked devices" }