List chats
Returns a page of the session's chats, served from the gateway's **stored copy** (not a live WhatsApp query), ordered for display. Page through results with `limit` and `cursor`: send the `nextCursor` from the previous response back as `cursor` to fetch the next page. When `nextCursor` is `null` there are no more chats. Requires the `read` capability. **Errors** - `not_found` (404): the session does not exist or is not owned by the caller's organization. - `forbidden` (403): the caller lacks the `read` capability.
Send Authorization: Bearer <token>. The router accepts two kinds of token and tries each in turn: a frontend-minted login JWT (verified against the frontend JWKS; the person's org + role are read from it), or an api-key for a script/service (carrying a fixed set of gateway permissions). The bearerFormat: JWT label describes the person-login case.
In: header
Path Parameters
The WhatsApp session id (a session is one attached WhatsApp number). The session must be owned by the caller's organization or the request fails with not_found.
Query Parameters
Maximum number of chats to return on one page. Clamped to the range 1–200; a missing or zero value defaults to 50.
int64Opaque pagination cursor. Pass the nextCursor value from the previous response to fetch the next page; treat it as a token and do not parse it. Omit it to get the first page.
Response Body
application/json
application/json
curl -X GET "https://example.com/api/v1/sessions/01HF.../chats"{ "data": [ { "archived": false, "id": 3344, "jid": "6281234567890@s.whatsapp.net", "lastMessageAt": 1719662400000, "mutedUntil": 1751198400000, "name": "Alice", "pinned": false, "sessionId": "01J9ZX8K2QHV0M3T6R7P4N5W8C", "type": "dm", "unreadCount": 3 } ], "nextCursor": "string"}{ "error": { "code": "not_found", "details": { "property1": null, "property2": null }, "message": "session not found" }}Unfollow a channel POST
Unsubscribe this session from the channel identified by `jid` so its posts stop arriving on this account. **Not implemented in v1.** This endpoint is wired but **always responds `501` with `not_implemented`** — no unfollow is performed and no state changes. **Authorization:** requires the `send` capability (`403` `forbidden` otherwise; `401` without a valid principal). **When implemented**, this will be an **idempotent** write: unfollowing a channel that is not followed is a no-op and still returns `204` (no content). The action takes no request body. **Errors:** `403` `forbidden` (missing `send`), `404` `not_found` (session or channel unknown), `501` `not_implemented` (current behavior).
Get a chat GET
Returns one chat by its id (`cid`, the chat JID), served from the gateway's **stored copy**. Use this to read a single chat's archive/pin/mute flags and unread count. Requires the `read` capability. **Errors** - `not_found` (404): the session does not exist, is not owned by the caller's organization, or no chat with that `cid` is stored for the session. - `forbidden` (403): the caller lacks the `read` capability.