Concepts

Concept	Meaning
App (tenant)	One entry in the gateway: a name, an API key, an optional webhook URL and one linked WhatsApp account.
Tenant API	Per-app endpoints (pairing, status, messages). Header x-api-key.
Admin API	Creates, lists and deletes apps, restarts clients, manages sessions. Header x-admin-key, or the dashboard's session cookie.
Provisioning API	Lets another product create and manage apps it owns. Header x-provisioning-key.
Session	The linked WhatsApp login. Encrypted with AES-256-GCM and stored in PostgreSQL, so restarts and new machines keep it.

App status

GET /api/status returns one of:

Status	Meaning
starting	The browser is launching.
qr	Waiting for a QR scan.
pairing	A phone-number pairing code was issued.
authenticated	Linked, finishing setup.
ready	Connected. You can send.
disconnected	Connection dropped. The gateway reconnects with backoff.
auth_failure	The stored login was rejected. Pair again.
error	The client failed to start. Restart it from the dashboard or Admin API.

A dropped connection keeps the stored session. Only a real logout (unlinked from the phone, Unlink, or POST /api/logout) deletes it.

Chat ids

Recipients can be a phone number in international format (spaces, dashes, + and a 00 prefix are fine), <number>@c.us, <id>@lid, or a group <id>@g.us. A local number starting with 0 is rejected because the country cannot be known.