Get a chat
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.
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.
The chat's JID (Jabber ID) — WhatsApp's address for a conversation. Format is 123...@s.whatsapp.net for a direct chat or 123...@g.us for a group.
Response Body
application/json
application/json
curl -X GET "https://example.com/api/v1/sessions/01HF.../chats/6281234567890@s.whatsapp.net"{ "archived": false, "id": 3344, "jid": "6281234567890@s.whatsapp.net", "lastMessageAt": 1719662400000, "mutedUntil": 1751198400000, "name": "Alice", "pinned": false, "sessionId": "01J9ZX8K2QHV0M3T6R7P4N5W8C", "type": "dm", "unreadCount": 3}{ "error": { "code": "not_found", "details": { "property1": null, "property2": null }, "message": "session not found" }}List chats GET
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.
Update a chat (archive/pin/mute) PATCH
Changes the archive, pin, and mute state of the chat in the path (`cid`) and returns the updated chat. **Partial update:** only the fields you send are changed; omitted fields stay as they are. - `archived` — set the chat's archived state. - `pinned` — set whether the chat is pinned to the top. - `mutedUntil` — mute until this instant, as Unix epoch **milliseconds**. - `unmute` — when `true`, clears any existing mute. Takes precedence over `mutedUntil`. Requires the `send` 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. - `validation_error` (422): the request body is malformed. - `forbidden` (403): the caller lacks the `send` capability.