Delete a chat
Removes the chat in the path (`cid`) from the gateway's **stored copy**, along with its locally stored messages. This is a **local delete only**: it does not delete the chat on WhatsApp, and the chat may reappear if new activity is later ingested for it. On success returns **204 No Content** with no body. 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. - `forbidden` (403): the caller lacks the `send` 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 to delete from the gateway's stored copy. Format is 123...@s.whatsapp.net for a direct chat or 123...@g.us for a group.
Response Body
application/json
curl -X DELETE "https://example.com/api/v1/sessions/01HF.../chats/6281234567890@s.whatsapp.net"{ "error": { "code": "not_found", "details": { "property1": null, "property2": null }, "message": "session not found" }}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.
List chat messages GET
Returns a page of messages in the chat named by `cid`, served from the gateway's **stored copy** (the message history the gateway has ingested), newest first. Page through results with `limit` and `cursor`: send the `nextCursor` from the previous response back as `cursor` to fetch the next (older) page. When `nextCursor` is `null` there are no more messages. 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. - `forbidden` (403): the caller lacks the `read` capability.