List stored channel messages
Return a page of **stored** messages for the channel identified by `jid` on this session, newest-first. This reads from the gateway's own message store — it returns what the gateway has already received and persisted for the channel, not a live fetch from WhatsApp. A channel the session has never received posts from yields an empty page. **Pagination:** use `limit` (1–200, default 50) and `cursor`. Omit `cursor` for the first page; read `nextCursor` from the response and pass it back to fetch the next page. The cursor is opaque — do not parse it. An empty `nextCursor` means the last page has been reached. **Authorization:** requires the `send` capability (`403` `forbidden` otherwise; `401` without a valid principal). This is a safe, side-effect-free read. **Errors:** `403` `forbidden` (missing `send`), `404` `not_found` (session or channel unknown).
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 (one attached WhatsApp number) whose stored channel messages are queried.
The channel's WhatsApp JID (a newsletter address, e.g. "120363012345678901@newsletter"). Percent-encode reserved characters such as "@" ("%40") in the path.
Query Parameters
Maximum number of messages to return on one page. Optional. Omitted or 0 defaults to 50; values are clamped to the range 1–200.
int64Opaque pagination cursor. Omit it for the first page; on each response read "nextCursor" and pass it back here to fetch the next page. Treat the value as a token — do not parse or construct it. An empty "nextCursor" in the response means there are no more pages.
Response Body
application/json
application/json
curl -X GET "https://example.com/api/v1/sessions/01HX.../channels/120363012345678901@newsletter/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" }}Create a channel (newsletter) POST
Create a WhatsApp **channel** (newsletter) owned by this session, returning its newly minted JID. **Not implemented in v1.** This endpoint is wired but the underlying WhatsApp operation is not yet built, so it **always responds `501` with `not_implemented`** — no channel is created and nothing is persisted. The request body shape below documents the eventual contract; today it is accepted but ignored. **Authorization:** requires the `send` capability; callers lacking it get `403` (`forbidden`). Requests without a valid principal get `401`. **When implemented**, this will be a write that creates a brand-new channel on the WhatsApp network; it is **not** idempotent (each successful call would create a distinct channel) and on success returns `201` with the channel's `jid`. **Errors:** `403` `forbidden` (missing `send`), `404` `not_found` (session unknown), `501` `not_implemented` (current behavior), and, once built, `400` `validation_error` for a missing/invalid `name`.
Follow a channel POST
Subscribe this session to the channel identified by `jid` so its posts arrive on this account. **Not implemented in v1.** This endpoint is wired but **always responds `501` with `not_implemented`** — no follow 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: following an already-followed channel 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).