Update a chat (archive/pin/mute)
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.
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 update. Format is 123...@s.whatsapp.net for a direct chat or 123...@g.us for a group.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Set the chat's archived state. Omit to leave it unchanged.
Mute the chat until this instant, expressed as Unix epoch milliseconds. Omit to leave the mute state unchanged. To unmute, send unmute:true instead of this field.
int64Set whether the chat is pinned to the top. Omit to leave it unchanged.
When true, clears any existing mute (overrides mutedUntil). Defaults to false.
Response Body
application/json
application/json
curl -X PATCH "https://example.com/api/v1/sessions/01HF.../chats/6281234567890@s.whatsapp.net" \ -H "Content-Type: application/json" \ -d '{}'{ "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" }}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.
Delete a chat DELETE
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.