List chat messages
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.
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 whose messages to list. Format is 123...@s.whatsapp.net for a direct chat or 123...@g.us for a group.
Query Parameters
Maximum number of messages 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 (older) 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/6281234567890@s.whatsapp.net/messages"{ "data": [ { "ackLevel": 3, "body": "Hello there!", "chatJid": "6281234567890@s.whatsapp.net", "createdAt": 1719662400000, "deleted": false, "direction": "in", "edited": false, "error": "recipient not on WhatsApp", "fromMe": false, "hasMedia": false, "id": "3EB0C431C26A1916E07A", "media": { "filename": "invoice.pdf", "mimetype": "image/jpeg", "size": 204800 }, "mentionNames": { "205227043110953": "Alice" }, "mentions": [ "205227043110953@lid" ], "quotedMessageId": "3EB0C431C26A1916E001", "senderJid": "6281234567890@s.whatsapp.net", "senderLid": "205227043110953@lid", "senderName": "Alice", "sessionId": "01J9ZX8K2QHV0M3T6R7P4N5W8C", "status": "delivered", "timestamp": 1719662400000, "type": "text", "waMessageId": "3EB0C431C26A1916E07A" } ], "nextCursor": "string"}{ "error": { "code": "not_found", "details": { "property1": null, "property2": null }, "message": "session not found" }}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.
Set chat presence (typing/recording) PUT
Broadcasts a typing/recording presence indicator to the chat in the path (`cid`). Set `state` to `composing` ("typing…"), `recording` ("recording audio…"), or `paused` (clear the indicator). **Live client required:** this goes straight to WhatsApp and needs a live, connected client for the session. If the session has no connected client, the call returns **501 `not_implemented`**. On success returns **204 No Content** with no body. The indicator is transient — WhatsApp clears it after a short timeout, so re-send periodically to keep it showing. Requires the `send` capability. **Errors** - `validation_error` (400/422): `state` is missing or not one of the allowed values. - `not_found` (404): the session does not exist or is not owned by the caller's organization. - `not_implemented` (501): the session has no connected WhatsApp client to deliver the presence. - `forbidden` (403): the caller lacks the `send` capability.