Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs: align the API reference and dashboard notes with the code
Yudhi Armyndharisdd13f3bed0a8
diff --git a/dashboard/src/pages/Chats.tsx b/dashboard/src/pages/Chats.tsxindex 8b5a821d2..0c41423d6 100644--- a/dashboard/src/pages/Chats.tsx+++ b/dashboard/src/pages/Chats.tsx@@ -716,7 +716,7 @@ export function Chats() {// The threads cache at staleTime: Infinity, and this session's events were not delivered while// another session was selected or the page was away. Mark them stale on a mount or a session switch// so the open one refetches and the others do when opened, with or without a live feed (a- // chat-scoped key is refused one).+ // chat-restricted key gets only its chats' message events).useEffect(() => {if (selectedSessionId) void queryClient.invalidateQueries({ queryKey: ['messages', selectedSessionId] });}, [selectedSessionId, queryClient]);diff --git a/docs/06-api-specification.md b/docs/06-api-specification.mdindex 4a9b26c74..83ac82701 100644--- a/docs/06-api-specification.md+++ b/docs/06-api-specification.md@@ -106,6 +106,11 @@ A few refusals add a stable machine-readable `code`, so a client can branch with| `IMPORT_WOULD_ORPHAN_ENGINES` | `409` | The backup lacks sessions running, starting or waiting to relaunch here; retry with `stopOrphans=true` or `force=true` || `IMPORT_NESTED_TRANSACTION` | `409` | Another database transaction is open on the connection; retry with no other data operation in flight || `EXPORT_IN_PROGRESS` | `409` | A data export is in progress; retry the import after it finishes |+| `IDEMPOTENCY_KEY_INVALID` | `400` | The `Idempotency-Key` header is not 1-255 visible ASCII characters |+| `IDEMPOTENCY_KEY_REUSED` | `422` | The key was already used for another route or body |+| `IDEMPOTENCY_KEY_IN_PROGRESS` | `409` | The first request with this key is still running; retry later with the same key |+| `IDEMPOTENCY_OUTCOME_UNKNOWN` | `409` | A failure may have sent the message; check the chat before sending again with a new key |+| `POLL_OPTION_NOT_FOUND` | `400` | None of the option texts match the poll; the body also carries `validOptions`, the texts it offers |Validation failures (`statusCode: 400`) return `message` as an **array** of field-level strings, with `error: "Bad Request"`, when field detail is enabled: by default outside production, or anywhere with `VALIDATION_ERROR_DETAIL=true`. Under `NODE_ENV=production` (the Docker image, compose and Helm default) detail is off unless that variable is set, and the body is only `{ "statusCode": 400, "message": "Bad Request" }`. Clients should accept `message` as either a string or an array of strings. A global `ValidationPipe` runs with `whitelist` + `forbidNonWhitelisted`, so any request-body field not declared on the DTO is rejected with `400`. A request whose path or query string contains `%00`, or whose body holds a NUL character (U+0000) in any string, is refused with `400` before the route runs. The body check does not cover three routes: `POST /api/infra/import-data` accepts a backup holding one and drops it from the stored text listed below and from template names, bodies, headers and footers and automation-rule names and replies, so a SQLite backup with a NUL there restores on PostgreSQL, the ingress route (`/api/ingress/:pluginId/:instanceId/:path`) reads its body raw and hands it to its plugin as delivered, and `POST /mcp` runs outside the Nest pipe chain, so a NUL in its tool input gets an in-band `BadRequestException` tool error instead of a `400`. Message text, captions, chat and contact names, media types and the account's own profile name received from WhatsApp, and dead-letter errors, are stored without NUL characters.@@ -1373,7 +1378,7 @@ GET /api/sessions/:sessionId/messages?since=1789855200000&until=1789941600000&or}```-Each `Message`: `{ id (uuid), sessionId, waMessageId (string|null), chatId, from, to, chatName (string|null; the sender's push name, or their saved contact name when no push name was reported), author (string|null; the real sender of a group, status or broadcast-list message, where from holds the group, status@broadcast or list id; on Baileys a list message the account received is filed under the sender, so from is the sender too), body (string|null), type, direction ('incoming'|'outgoing'), timestamp (number|null), metadata (object|null), mediaPath (string|null; storage key of archived media), mediaMimetype (string|null), status ('pending'|'sent'|'delivered'|'read'|'failed'), createdAt (ISO date) }`. By default, ordered by `createdAt` DESC, then by a dialect-dependent second key. The tiebreaker matters: `createdAt` is not unique (SQLite stores whole seconds, a PostgreSQL bulk write ties every row it inserts, and a history backfill carries WhatsApp's own second-resolution timestamp), and without a total order two pages of one walk can repeat a row and omit another. On SQLite the second key is `rowid`, the stored insertion sequence, so messages sharing a second come back in the order they arrived. PostgreSQL has no equivalent (`ctid` moves on every ack update), so it keeps `id`, a random uuid: the walk is equally correct there, but a same-second group is not in arrival order. Note that `offset` still addresses a position by count, so a list taking concurrent writes can shift under a walk: a message arriving mid-walk pushes every older row down one, and the next page re-serves a row the previous one already returned. Pass `after` instead to walk a live chat safely; it anchors on the last row you received, which an arriving message cannot move. The response is the raw service object (no envelope). Unlike the live `IncomingMessage` shape below, this persisted `Message` does **not** carry `kind` — re-derive the chat kind from `chatId` (see `ChatKind` / `chatKind()`) if needed. When present, `metadata` may include `media`, `quotedMessage`, `call`, `reactions`, and, for Baileys inbound business prompts, `buttons: [{ id, text }, …]` so a client (including the dashboard Chats thread) can re-render the choices after reload and tap them via [`POST .../click-button`](#post-apisessionssessionidmessagesclick-button).+Each `Message`: `{ id (uuid), sessionId, waMessageId (string|null), chatId, from, to, chatName (string|null; the sender's push name, or their saved contact name when no push name was reported), author (string|null; the real sender of a group, status or broadcast-list message, where from holds the group, status@broadcast or list id; on Baileys a list message the account received is filed under the sender, so from is the sender too), body (string|null), type, direction ('incoming'|'outgoing'), timestamp (number|null), metadata (object|null), mediaPath (string|null; storage key of archived media), mediaMimetype (string|null), status ('pending'|'sent'|'delivered'|'read'|'failed'), createdAt (ISO date) }`. By default, ordered by `createdAt` DESC, then by a dialect-dependent second key. The tiebreaker matters: `createdAt` is not unique (SQLite stores whole seconds, a PostgreSQL bulk write ties every row it inserts, and a history backfill carries WhatsApp's own second-resolution timestamp), and without a total order two pages of one walk can repeat a row and omit another. On SQLite the second key is `rowid`, the stored insertion sequence, so messages sharing a second come back in the order they arrived. PostgreSQL has no equivalent (`ctid` moves on every ack update), so it keeps `id`, a random uuid: the walk is equally correct there, but a same-second group is not in arrival order. Note that `offset` still addresses a position by count, so a list taking concurrent writes can shift under a walk: a message arriving mid-walk pushes every older row down one, and the next page re-serves a row the previous one already returned. Pass `after` instead to walk a live chat safely; it anchors on the last row you received, which an arriving message cannot move. The response is the raw service object (no envelope). Unlike the live `IncomingMessage` shape below, this persisted `Message` does **not** carry `kind` — re-derive the chat kind from `chatId` (see `ChatKind` / `chatKind()`) if needed. When present, `metadata` may include `media`, `quotedMessage`, `call`, `reactions`, and, for Baileys inbound business prompts, `poll { name, options, allowMultipleAnswers }` for a poll creation message, `buttons: [{ id, text }, …]` so a client (including the dashboard Chats thread) can re-render the choices after reload and tap them via [`POST .../click-button`](#post-apisessionssessionidmessagesclick-button).> **Inline media is carried up to a budget, then omitted.** `MESSAGE_LIST_INLINE_MEDIA_BUDGET_BYTES` (8 MiB of encoded base64 by default) bounds how much inline media one response may hold across its rows. A row is not a bounded object, `limit` is clamped to `[1,100]` but each row can carry its base64 in `metadata.media.data`, so a page of media rows could otherwise reach hundreds of megabytes and fail the read outright. The budget is spent newest-first, matching the selected descending order, so a page that cannot carry everything keeps the most recent media. Past it a payload is replaced with `{ mimetype, filename?, omitted: true, sizeBytes }`, the same marker the engine emits for inbound media over `MEDIA_DOWNLOAD_MAX_BYTES`, and the bytes remain available from [`GET /messages/:chatId/:messageId/media`](#get-apisessionssessionidmessageschatidmessageidmedia). Two rules bound the edges: the newest payload is always inlined even when it alone exceeds the budget (otherwise a single large photo would be permanently unreadable through this route), and a budget of `0` means "never inline" and grants no such allowance. The knob is validated at boot, `8MiB` would parse to 8 bytes, and is forwarded by both compose files. The MCP `MessageList` tool shares this path and the same budget. A row stored under `MESSAGE_INLINE_MEDIA=archive` arrives with the marker already in place, plus `archived: true`, its bytes live only in the chat-media archive, behind the same media route (see that route for the mode).@@ -1426,7 +1431,7 @@ Returns a bare array of engine-neutral `IncomingMessage` objects: the chat's mos]```-Each item may also include `isStatusBroadcast`, `mentionedIds`, `isLidSender`, `ephemeralDuration` (the chat's disappearing-messages timer in seconds, present only when one is set), `contact`, `media { mimetype, filename?, data?, omitted?, sizeBytes? }`, `quotedMessage { id, body }`, `call { video, missed }` (for `call` messages), `location { latitude, longitude, description?, address?, url? }`, `order { orderId, token? }` (for `order` messages) and `product { productId, title?, description?, businessOwnerJid? }` (for `product` messages). `senderPhone` is **not** among them: this endpoint reads live from the engine and performs no privacy-id resolution, which runs only on the inbound `message.received` path (§6.6). To map an `@lid` sender seen here, call `GET /api/sessions/:sessionId/contacts/:contactId/phone`. `type` is one of `text|image|video|audio|voice|document|sticker|location|contact|poll|call|revoked|order|product|masked|unknown`. An `order` is a cart the customer placed from the business catalog and a `product` is a single catalog product shared into the chat. Only whatsapp-web.js serves this route (Baileys answers `501`), so every `order` and `product` block here comes from that engine. The message carries no line items and this API exposes no order lookup, so `orderId` plus the single-order `token` are a correlation handle you redeem elsewhere. The catalog routes answer `501` on whatsapp-web.js, so a `productId` read here does not resolve through them. whatsapp-web.js exposes no catalog field and cannot tell a share of a whole catalog from a product: a `product` message without a product id arrives with no `product` block. On Baileys the blocks arrive on `message.received`, where `GET /api/sessions/:sessionId/catalog/products/:productId` resolves a `productId` only when the product came from the session's own catalog (`businessOwnerJid` says whose it is), and a share of a whole catalog is typed `unknown`, both live and in the rows history sync stores. A Baileys `message.received` may also carry `button { id, text? }` when the sender tapped a WhatsApp Business button, template quick-reply, list row, or native-flow control (this live-history route never sees it, since Baileys answers `501` here). A `masked` message is one WhatsApp deliberately withholds from linked/companion devices — e.g. a high-security business OTP — so its `body` is empty by design (the content is only available on the primary phone) rather than a parsing failure; this occurs on the Baileys engine. `kind` is the user-facing chat discriminator of `chatId` — one of `individual|group|channel|status|broadcast|unknown`; it supersedes `isStatusBroadcast` (equivalent to `kind === 'status'`), which is retained for back-compat.+Each item may also include `isStatusBroadcast`, `mentionedIds`, `isLidSender`, `ephemeralDuration` (the chat's disappearing-messages timer in seconds, present only when one is set), `contact`, `media { mimetype, filename?, data?, omitted?, sizeBytes? }`, `quotedMessage { id, body }`, `call { video, missed }` (for `call` messages), `location { latitude, longitude, description?, address?, url? }`, `order { orderId, token? }` (for `order` messages) `product { productId, title?, description?, businessOwnerJid? }` (for `product` messages) and `poll { name, options, allowMultipleAnswers }` (for poll creation messages, when the engine provides the choices). `senderPhone` is **not** among them: this endpoint reads live from the engine and performs no privacy-id resolution, which runs only on the inbound `message.received` path (§6.6). To map an `@lid` sender seen here, call `GET /api/sessions/:sessionId/contacts/:contactId/phone`. `type` is one of `text|image|video|audio|voice|document|sticker|location|contact|poll|call|revoked|order|product|masked|unknown`. An `order` is a cart the customer placed from the business catalog and a `product` is a single catalog product shared into the chat. Only whatsapp-web.js serves this route (Baileys answers `501`), so every `order` and `product` block here comes from that engine. The message carries no line items and this API exposes no order lookup, so `orderId` plus the single-order `token` are a correlation handle you redeem elsewhere. The catalog routes answer `501` on whatsapp-web.js, so a `productId` read here does not resolve through them. whatsapp-web.js exposes no catalog field and cannot tell a share of a whole catalog from a product: a `product` message without a product id arrives with no `product` block. On Baileys the blocks arrive on `message.received`, where `GET /api/sessions/:sessionId/catalog/products/:productId` resolves a `productId` only when the product came from the session's own catalog (`businessOwnerJid` says whose it is), and a share of a whole catalog is typed `unknown`, both live and in the rows history sync stores. A Baileys `message.received` may also carry `button { id, text? }` when the sender tapped a WhatsApp Business button, template quick-reply, list row, or native-flow control (this live-history route never sees it, since Baileys answers `501` here). A `masked` message is one WhatsApp deliberately withholds from linked/companion devices — e.g. a high-security business OTP — so its `body` is empty by design (the content is only available on the primary phone) rather than a parsing failure; this occurs on the Baileys engine. `kind` is the user-facing chat discriminator of `chatId` — one of `individual|group|channel|status|broadcast|unknown`; it supersedes `isStatusBroadcast` (equivalent to `kind === 'status'`), which is retained for back-compat.**Errors:** `400` session not active · `401` missing/invalid API key · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine · `503` the whatsapp-web.js page died mid-read (retryable)@@ -1457,23 +1462,23 @@ Returns a bare array of `MessageReaction`:]```-**Errors:** `400` session not active · `401` missing/invalid API key · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine · `503` the whatsapp-web.js page died mid-read (retryable)--Poll creation messages include `poll { name, options, allowMultipleAnswers }` when the engine provides the choices. Live `message.received` and `message.sent` events and whatsapp-web.js history carry it at the top level. Stored-message responses carry the same object in `metadata.poll`, including polls sent through `send-poll`. The dashboard displays these option texts. Use the exact strings in `options` when voting; their order and whitespace are preserved.--Legacy stored polls may have no choices because they were captured before this field was stored. Vote counts are not included.+**Errors:** `400` session not active · `401` missing/invalid API key · `404` message not found in the chat (whatsapp-web.js) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine · `503` the whatsapp-web.js page died mid-read (retryable)#### POST /api/sessions/:sessionId/messages/vote-pollCast a vote on a poll.+Poll creation messages include `poll { name, options, allowMultipleAnswers }` when the engine provides the choices. Live `message.received` and `message.sent` events and whatsapp-web.js history carry it at the top level. Stored-message responses carry the same object in `metadata.poll`, including polls sent through `send-poll`. The dashboard displays these option texts. Use the exact strings in `options` when voting; their order and whitespace are preserved.++Legacy stored polls may have no choices because they were captured before this field was stored. Vote counts are not included.+**Auth:** API key (OPERATOR) · **Engines:** whatsapp-web.js only — Baileys returns `501`**Body**| Field | Type | Required | Description || ------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- |-| chatId | string | yes | Chat containing the poll |+| chatId | string | yes | Chat containing the poll (max 255 characters) || pollMessageId | string | yes | The poll creation message || options | string[] | yes | The option **texts** to select, exactly as they appear on the poll (max 12). Replaces the current selection; `[]` clears the vote |@@ -1508,7 +1513,7 @@ Pin a message in its chat for a bounded window.| Field | Type | Required | Description || --------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |-| chatId | string | yes | Chat containing the message |+| chatId | string | yes | Chat containing the message (max 255 characters) || messageId | string | yes | Message to pin || durationSeconds | number | no | `86400` (24h), `604800` (7d) or `2592000` (30d). Defaults to `86400`. Any other value is rejected with `400` — WhatsApp recognises no others. |@@ -1528,11 +1533,11 @@ never sees it — and unlike pinning it has no group-admin restriction and never**Body**-| Field | Type | Required | Description |-| --------- | ------- | -------- | ------------------------------------------ |-| chatId | string | yes | Chat containing the message |-| messageId | string | yes | Message to star or unstar |-| star | boolean | yes | `true` to star, `false` to remove the star |+| Field | Type | Required | Description |+| --------- | ------- | -------- | ------------------------------------------------ |+| chatId | string | yes | Chat containing the message (max 255 characters) |+| messageId | string | yes | Message to star or unstar |+| star | boolean | yes | `true` to star, `false` to remove the star |**Response** `200` — `{ "success": true }`@@ -1551,10 +1556,10 @@ Remove a message's pin. Takes no duration.**Body**-| Field | Type | Required | Description |-| --------- | ------ | -------- | --------------------------- |-| chatId | string | yes | Chat containing the message |-| messageId | string | yes | Message to unpin |+| Field | Type | Required | Description |+| --------- | ------ | -------- | ------------------------------------------------ |+| chatId | string | yes | Chat containing the message (max 255 characters) |+| messageId | string | yes | Message to unpin |**Response** `200` — `{ "success": true }`@@ -1745,14 +1750,14 @@ Send a plain text message.**Request body** — `SendTextMessageDto`-| Field | Type | Required | Constraints | Description |-| ----------------- | -------- | -------- | ------------------------------ | -------------------------------------------------------------------------------------------- |-| chatId | string | Yes | non-empty, max 255 | `[email protected]` or `[email protected]` |-| text | string | Yes | non-empty, max 4096 | Message text |-| mentions | string[] | No | array of WIDs | WIDs to @mention (e.g. `["[email protected]"]`). See **Mentions** below |-| linkPreview | boolean | No | — | `false` suppresses it; on Baileys `true` is required to get one. See **Link previews** below |-| customLinkPreview | object | No | `{ url, title, description? }` | Attach a preview you supply. **Baileys only.** See **Link previews** below |-| quotedMessageId | string | No | non-empty | Quote an earlier message, making this a reply. See [Quoted sends](#quoted-sends) below |+| Field | Type | Required | Constraints | Description |+| ----------------- | -------- | -------- | ---------------------------------------- | -------------------------------------------------------------------------------------------- |+| chatId | string | Yes | non-empty, max 255 | `[email protected]` or `[email protected]` |+| text | string | Yes | non-empty, max 4096 | Message text |+| mentions | string[] | No | array of WIDs, max 1024 of 64 characters | WIDs to @mention (e.g. `["[email protected]"]`). See **Mentions** below |+| linkPreview | boolean | No | — | `false` suppresses it; on Baileys `true` is required to get one. See **Link previews** below |+| customLinkPreview | object | No | `{ url, title, description? }` | Attach a preview you supply. **Baileys only.** See **Link previews** below |+| quotedMessageId | string | No | non-empty | Quote an earlier message, making this a reply. See [Quoted sends](#quoted-sends) below |```json{ "chatId": "[email protected]", "text": "Hello from OpenWA!" }@@ -1877,7 +1882,7 @@ Render a stored text template (header/body/footer joined by blank lines, `{{vars| templateId | string | Conditional | non-empty; required when `templateName` is absent | Stored template id || templateName | string | Conditional | non-empty; required when `templateId` is absent | Stored template name || vars | Record\<string,string\> | No | object | Substituted into `{{placeholder}}` tokens; defaults to `{}` |-| mentions | string[] | No | array of WIDs | WIDs to @mention in the rendered body |+| mentions | string[] | No | array of WIDs, max 1024 of 64 characters | WIDs to @mention in the rendered body || linkPreview | boolean | No | — | Same engine split as `send-text`; see **Link previews** |```json@@ -1912,16 +1917,16 @@ Send an image (by URL or base64) with an optional caption.**Request body** — `SendMediaMessageDto`-| Field | Type | Required | Constraints | Description |-| --------------- | -------- | ----------- | ------------------------------------- | ---------------------------------------------------------------------------------------- |-| chatId | string | Yes | non-empty, max 255 | Target chat |-| url | string | Conditional | URL; required when `base64` is absent | http/https media URL (SSRF-guarded; a blocked internal or unreachable URL maps to `400`) |-| base64 | string | Conditional | string; required when `url` is absent | Base64 media data (capped to the media byte limit) |-| mimetype | string | Conditional | string; required when using `base64` | MIME type of the media |-| filename | string | No | max 255 | File name |-| caption | string | No | max 1024 | Caption text |-| mentions | string[] | No | array of WIDs | WIDs to @mention in the caption. See **Mentions** above |-| quotedMessageId | string | No | non-empty | Quote an earlier message, making this a reply — see [Quoted sends](#quoted-sends) |+| Field | Type | Required | Constraints | Description |+| --------------- | -------- | ----------- | ---------------------------------------- | ---------------------------------------------------------------------------------------- |+| chatId | string | Yes | non-empty, max 255 | Target chat |+| url | string | Conditional | URL; required when `base64` is absent | http/https media URL (SSRF-guarded; a blocked internal or unreachable URL maps to `400`) |+| base64 | string | Conditional | string; required when `url` is absent | Base64 media data (capped to the media byte limit) |+| mimetype | string | Conditional | string; required when using `base64` | MIME type of the media |+| filename | string | No | max 255 | File name |+| caption | string | No | max 1024 | Caption text |+| mentions | string[] | No | array of WIDs, max 1024 of 64 characters | WIDs to @mention in the caption. See **Mentions** above |+| quotedMessageId | string | No | non-empty | Quote an earlier message, making this a reply — see [Quoted sends](#quoted-sends) |```json{ "chatId": "[email protected]", "url": "https://example.com/image.jpg", "caption": "Check out this image!" }@@ -2039,8 +2044,8 @@ Send a location pin.| chatId | string | Yes | non-empty, max 255 | Target chat || latitude | number | Yes | valid latitude | Latitude (out-of-range → `400`) || longitude | number | Yes | valid longitude | Longitude (out-of-range → `400`) |-| description | string | No | string | Pin description |-| address | string | No | string | Pin address |+| description | string | No | string, max 1024 | Pin description |+| address | string | No | string, max 1024 | Pin address || quotedMessageId | string | No | non-empty | Quote an earlier message, making this a reply — see [Quoted sends](#quoted-sends) |```json@@ -2078,8 +2083,8 @@ Send a contact card (vCard).| Field | Type | Required | Constraints | Description || --------------- | ------ | -------- | ------------------ | --------------------------------------------------------------------------------- || chatId | string | Yes | non-empty, max 255 | Target chat |-| contactName | string | Yes | non-empty | Display name for the contact card |-| contactNumber | string | Yes | non-empty | Contact phone number |+| contactName | string | Yes | non-empty, max 255 | Display name for the contact card |+| contactNumber | string | Yes | non-empty, max 30 | Contact phone number || quotedMessageId | string | No | non-empty | Quote an earlier message, making this a reply — see [Quoted sends](#quoted-sends) |```json@@ -2173,12 +2178,12 @@ Reply to a message, quoting a prior message.**Request body** — `ReplyMessageDto`-| Field | Type | Required | Constraints | Description |-| --------------- | -------- | -------- | ------------------ | ---------------------------------------- |-| chatId | string | Yes | non-empty, max 255 | Target chat |-| quotedMessageId | string | Yes | non-empty | WhatsApp id of the message being quoted |-| text | string | Yes | non-empty | Reply text |-| mentions | string[] | No | array of WIDs | WIDs to @mention. See **Mentions** above |+| Field | Type | Required | Constraints | Description |+| --------------- | -------- | -------- | ---------------------------------------- | ---------------------------------------- |+| chatId | string | Yes | non-empty, max 255 | Target chat |+| quotedMessageId | string | Yes | non-empty | WhatsApp id of the message being quoted |+| text | string | Yes | non-empty, max 4096 | Reply text |+| mentions | string[] | No | array of WIDs, max 1024 of 64 characters | WIDs to @mention. See **Mentions** above |```json{ "chatId": "[email protected]", "quotedMessageId": "[email protected]_3EB0ABCD", "text": "Replying to you" }@@ -2285,11 +2290,11 @@ Add or remove a reaction to a message (an empty emoji removes the reaction).**Request body** — `ReactMessageDto`-| Field | Type | Required | Constraints | Description |-| --------- | ------ | -------- | --------------------- | -------------------------------------------------------------------------------- |-| chatId | string | Yes | non-empty, max 255 | Target chat |-| messageId | string | Yes | non-empty | Message to react to |-| emoji | string | Yes | string (may be empty) | Reaction emoji; an empty string removes the reaction. The field must be present. |+| Field | Type | Required | Constraints | Description |+| --------- | ------ | -------- | ----------------------------- | -------------------------------------------------------------------------------- |+| chatId | string | Yes | non-empty, max 255 | Target chat |+| messageId | string | Yes | non-empty | Message to react to |+| emoji | string | Yes | string (may be empty), max 32 | Reaction emoji; an empty string removes the reaction. The field must be present. |```json{ "chatId": "[email protected]", "messageId": "[email protected]_3EB0ABCD", "emoji": "👍" }@@ -2353,12 +2358,12 @@ Edit the text of a message sent by this account; also updates the stored record'**Request body** — `EditMessageDto`-| Field | Type | Required | Constraints | Description |-| --------- | -------- | -------- | ----------------------- | ------------------------------------------------- |-| chatId | string | Yes | non-empty, max 255 | Chat containing the message |-| messageId | string | Yes | non-empty | Message to edit (the send response's `messageId`) |-| body | string | Yes | non-empty, ≤ 4096 chars | New text content |-| mentions | string[] | No | array of WIDs | Re-applies participant tags to the new body |+| Field | Type | Required | Constraints | Description |+| --------- | -------- | -------- | ---------------------------------------- | ------------------------------------------------- |+| chatId | string | Yes | non-empty, max 255 | Chat containing the message |+| messageId | string | Yes | non-empty | Message to edit (the send response's `messageId`) |+| body | string | Yes | non-empty, ≤ 4096 chars | New text content |+| mentions | string[] | No | array of WIDs, max 1024 of 64 characters | Re-applies participant tags to the new body |```json{ "chatId": "[email protected]", "messageId": "[email protected]_3EB0ABCD", "body": "Corrected text" }@@ -2929,7 +2934,7 @@ Get the group invite code and full invite link. The code is a transferable join}```-**Errors:** `400` session is not started · `401` missing/invalid `X-API-Key` · `403` key lacks OPERATOR role, or the engine refused (admin rights required) · `409` conflict or engine not ready (retryable) · `503` session not ready or dependency unavailable (retryable); on Baileys, also when WhatsApp rate-limits or times out the request (code 429 or 408): retry after a pause+**Errors:** `400` session is not started · `401` missing/invalid `X-API-Key` · `403` key lacks OPERATOR role, or the engine refused (admin rights required) · `404` no such group · `409` conflict or engine not ready (retryable) · `503` session not ready or dependency unavailable (retryable); on Baileys, also when WhatsApp rate-limits or times out the request (code 429 or 408): retry after a pause#### POST /api/sessions/:sessionId/groups@@ -3370,7 +3375,7 @@ Update group settings. Each present field maps to one engine call; absent fields{ "success": true, "message": "Group settings updated" }```-**Errors:** `400` session is not started / empty patch / unknown body field · `401` missing/invalid `X-API-Key` · `403` key lacks OPERATOR role, the account is not a group admin (`memberAddMode` on whatsapp-web.js), or a key restricted to selected chats names a group outside its allowlist · `501` `ephemeralSeconds` on the whatsapp-web.js engine (library limitation) · `409` conflict or engine not ready (retryable) · `503` session not ready or dependency unavailable (retryable); on Baileys, also when WhatsApp rate-limits or times out the request (code 429 or 408): retry after a pause+**Errors:** `400` session is not started / empty patch / unknown body field · `401` missing/invalid `X-API-Key` · `403` key lacks OPERATOR role, the account is not a group admin (`memberAddMode` on whatsapp-web.js), or a key restricted to selected chats names a group outside its allowlist · `404` group not found · `501` `ephemeralSeconds` on the whatsapp-web.js engine (library limitation) · `409` conflict or engine not ready (retryable) · `503` session not ready or dependency unavailable (retryable); on Baileys, also when WhatsApp rate-limits or times out the request (code 429 or 408): retry after a pause#### GET /api/sessions/:sessionId/groups/:groupId/membership-requests@@ -5474,6 +5479,8 @@ Public liveness probe. It answers `200` through the shutdown drain and `503` fro{ "status": "ok", "timestamp": "2026-06-25T12:00:00.000Z" }```+**Errors:** `503` shutdown teardown has begun+---#### GET /api/infra/status@@ -5735,10 +5742,10 @@ Request a graceful server restart, optionally orchestrating Docker profiles (add**Request body** — optional `RestartDto` (class-validated; unknown fields and non-string array members reject)-| Field | Type | Required | Default | Description |-| ------------------ | -------- | -------- | ------- | ------------------------------------------------------------------- |-| `profiles` | string[] | No | `[]` | Docker profiles to enable/start (e.g. `postgres`, `redis`, `minio`) |-| `profilesToRemove` | string[] | No | `[]` | Docker profiles whose containers should be stopped/removed |+| Field | Type | Required | Default | Description |+| ------------------ | -------- | -------- | ------- | -------------------------------------------------------------------- |+| `profiles` | string[] | No | `[]` | Docker profiles to enable/start (e.g. `postgres`, `redis`, `minio`) |+| `profilesToRemove` | string[] | No | `[]` | Docker profiles whose containers are stopped and kept, never deleted |```json{ "profiles": ["postgres", "redis"], "profilesToRemove": ["minio"] }@@ -6500,18 +6507,18 @@ Search messages across sessions (active search provider).**Query parameters**-| Name | Type | Required | Default | Description |-| ----------- | ------------------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| `q` | string | **Yes** | — | Search term. Must be non-empty after trim; `400` for whitespace-only, over 1000 characters, or over 32 words (punctuation separates words, each symbol is a word, a repeated word counts once). Passed to the active provider's native full-text matcher. |-| `sessionId` | string | No | — | Restrict to a single session id (intersected with the key's `allowedSessions` scope). |-| `chatId` | string | No | — | Restrict to a single chat id. For a key restricted to selected chats this must name an allowed chat (`403` otherwise), and its hits are additionally narrowed to the allowlist. |-| `direction` | enum (`incoming` \| `outgoing`) | No | — | Filter by message direction. |-| `type` | string | No | — | Filter by stored message `type` (e.g. `text`, `image`, `video`). Compared against `messages.type`; not an enum validation, any string is accepted and unmatched values simply return no hits. |-| `from` | string | No | — | Filter by sender. |-| `dateFrom` | integer (epoch ms) | No | — | Inclusive lower bound on `timestamp`. A non-numeric value is rejected with `400`. |-| `dateTo` | integer (epoch ms) | No | — | Inclusive upper bound on `timestamp`. A non-numeric value is rejected with `400`. |-| `limit` | integer (≥ 1) | No | `50` | Max hits to return. Clamped to `SEARCH_LIMIT_MAX` (default `100`). A non-integer value is rejected with `400`. |-| `offset` | integer (≥ 0) | No | `0` | Pagination offset, at most `100000`. A non-integer or larger value is rejected with `400`. |+| Name | Type | Required | Default | Description |+| ----------- | ------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `q` | string | **Yes** | — | Search term. Must be non-empty after trim; `400` for whitespace-only, over 1000 characters, or over 32 words (punctuation separates words, each symbol is a word, a whitespace-separated word said again counts once). Passed to the active provider's native full-text matcher. |+| `sessionId` | string | No | — | Restrict to a single session id (intersected with the key's `allowedSessions` scope). |+| `chatId` | string | No | — | Restrict to a single chat id. For a key restricted to selected chats this must name an allowed chat (`403` otherwise), and its hits are additionally narrowed to the allowlist. |+| `direction` | enum (`incoming` \| `outgoing`) | No | — | Filter by message direction. |+| `type` | string | No | — | Filter by stored message `type` (e.g. `text`, `image`, `video`). Compared against `messages.type`; not an enum validation, any string is accepted and unmatched values simply return no hits. |+| `from` | string | No | — | Filter by sender. |+| `dateFrom` | integer (epoch ms) | No | — | Inclusive lower bound on `timestamp`. A non-numeric value is rejected with `400`. |+| `dateTo` | integer (epoch ms) | No | — | Inclusive upper bound on `timestamp`. A non-numeric value is rejected with `400`. |+| `limit` | integer (≥ 1) | No | `50` | Max hits to return. Clamped to `SEARCH_LIMIT_MAX` (default `100`). A non-integer value is rejected with `400`. |+| `offset` | integer (≥ 0) | No | `0` | Pagination offset, at most `100000`. A non-integer or larger value is rejected with `400`. |**Response** `200` — `SearchResults`@@ -7204,30 +7211,30 @@ Every registered webhook receives an HTTP `POST` with a JSON body of this shape:These are the events OpenWA actually emits. A webhook is registered with an `events` list; an event is delivered to a webhook when its `events` array includes the event name or `"*"`.-| Event | When it fires | `data` payload sketch |-| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| `message.received` | An inbound message arrives | The full message object: `id`, `from`, `to`, `body`, `type`, `timestamp` (epoch **seconds**), `isGroup`, `kind` (user-facing chat discriminator of `chatId` — `individual\|group\|channel\|status\|broadcast\|unknown`), `fromMe`, `chatId`, `media{mimetype,filename?,data?,omitted?,sizeBytes?}` (media messages only), `contact{…}` (plus optional `senderPhone` for `@lid` senders, `order{orderId,token?}` / `product{productId,…}` on `order` / `product` messages, `buttons:[{id,text}]` on a WhatsApp Business prompt that offers choices, and `button{id,text?}` when the sender tapped one; **Baileys only**) |-| `message.sent` | An outbound message is created/sent from this session | Same message object shape as `message.received` |-| `message.ack` | A delivery/read receipt updates an outbound message. On Baileys only 1:1 receipts arrive: it reports group and status receipts per participant, which are not consumed, so an own group or status message stays at `sent`, see below | `{ id, messageId, status, ack, chatId? }` — `status` is the canonical state (`pending`/`sent`/`delivered`/`read`/`failed`); `ack` is the deprecated legacy integer derived from it; `chatId` is the conversation the acked message belongs to, present whenever the engine's update names the chat (both engines do on the live path) |-| `message.failed` | A receipt resolves to `failed` (dispatched in addition to `message.ack`) | `{ id, messageId, status: "failed", ack: -1, chatId? }`; `chatId` follows the same rules as `message.ack` |-| `message.revoked` | A message is deleted/recalled | `{ id, revokedId?, chatId, from, to, type: "revoked", body: "", timestamp }` — **reconcile on `revokedId`** (the original deleted message's id), falling back to `id`. On whatsapp-web.js `id` is the _revocation notification_ (a distinct message that won't match a stored id) and `revokedId` may be absent when the original isn't cached locally; on Baileys the two coincide |-| `message.reaction` | A reaction is added, changed, or removed | `{ messageId, chatId, reaction, senderId, reactions? }` — `reactions` is the post-apply `{ senderId: emoji }` snapshot, omitted when the gateway holds no stored copy of the message to compute it from (an ephemeral message, or one predating the session going live); treat it as unknown rather than empty and keep the map you already hold. `reaction` is empty when removed |-| `message.edited` | A message body or media caption is edited | `{ messageId, chatId, body, senderId, from, to, fromMe, isGroup, type, hasMedia, author?, mentionedIds?, timestamp }` — `messageId` is the original message id, `body` is the latest text/caption, and `timestamp` is the edit occurrence time in epoch **seconds** (not the original creation time) |-| `session.qr` | A new pairing QR is generated | `{ sessionId, qr }` — `qr` is a **PNG data URL** (`data:image/png;base64,…`), the same rendered value `GET /api/sessions/{sessionId}/qr` returns as `qrCode`, not the raw `2@…` linking ref. Render it directly in an `<img src>`; the raw ref never leaves the engine adapter |-| `session.authenticated` | The session pairs and becomes ready | `{ sessionId, phone, pushName }` |-| `session.disconnected` | The session disconnects on the engine or WhatsApp side (drop, conflict, or a phone-initiated unlink). Not fired for API-initiated stop/logout/delete — those are acknowledged by the API response and the `session.status` transition | `{ sessionId, reason }` |-| `session.reconnect_loop` | Every 5th consecutive reconnect attempt is scheduled (attempt 5, 10, 15, …) — the session is failing to come back up | `{ sessionId, attempts, nextDelayMs }` |-| `presence.update` | A subscribed chat's presence changed — someone came online, started typing, or stopped. Only actual CHANGES are dispatched: WhatsApp repeats itself freely, and every repeat would otherwise be a delivery | `{ sessionId, chatId, participants: [{ id, state, lastSeen? }], groupOnlineCount? }` — `state` is `available`/`unavailable`/`composing`/`recording`/`paused`; `lastSeen` is epoch **seconds** and absent when the contact hides it. Requires `POST .../presence/subscribe` first, and Baileys — whatsapp-web.js cannot observe presence |-| `event.response` | A guest answered a WhatsApp event invitation (going, not going, maybe). **Baileys only**; see the payload note below | `{ sessionId, eventMessageId, chatId, responderId, contact?, fromMe, response, extraGuestCount?, eventName?, responseMessageId, timestamp }`. `response` is `going`/`not_going`/`maybe`/`unknown`; `timestamp` is epoch **seconds** on the guest's clock. Order a guest's answers by `timestamp`, not by delivery |-| `session.restriction` | WhatsApp places a restriction on the account, or lifts one. Deduped: an unchanged restriction is not re-announced, and a lift is only sent when one was in force | `{ sessionId, active, kind, code, expiresAt }` — `active` is `false` for a lift and `kind`/`code` then describe the restriction that ended; `expiresAt` is an ISO timestamp or `null`. See `restriction` on the session response for the `kind` values |-| `session.status` | The session status transitions | `{ sessionId, status }` where `status` is one of `created` / `initializing` / `qr_ready` / `authenticating` / `ready` / `disconnected` / `action_required` / `failed` |-| `group.join` | Participant(s) are added to or join a group this session is in | `{ groupId, actorId?, participantIds, timestamp }`. `actorId` is the admin/inviter when known. **Baileys**: a session added to or joining a group reports only its own id in `participantIds` (members added with it are not listed) |-| `group.leave` | Participant(s) leave or are removed from a group | `{ groupId, actorId?, participantIds, timestamp }` |-| `group.update` | Group metadata changes (subject, description, announce/locked settings) | `{ groupId, actorId?, participantIds, changes?, timestamp }` — `changes` carries only the fields that changed: `subject?`, `description?`, `announce?`, `locked?` |-| `group.join_request` | Someone asked to join a group this session administers (join-approval mode on) | `{ groupId, actorId?, participantIds, timestamp }` — `participantIds` are the users asking to join; `actorId` is who created the request when the engine reports one (differs from the requester on a non-admin add). Act on it via `GET/POST .../groups/:groupId/membership-requests[...]` **Baileys caveat**: the library (7.0.0-rc14) emits this only for non-admin-add requests — an invite-link self-request may produce no event there (upstream TODO); the membership-requests list endpoint still reports it. |-| `call.received` | An incoming voice/video call starts ringing. Dispatched by both engines, but **not reliable on whatsapp-web.js**: it fired in a live test on 2026-09-17 and did not in one on 2026-08-10 | `{ callId, from, isVideo, isGroup, timestamp }` — `callId` is the id to pass to `POST /sessions/:sessionId/calls/:callId/reject` (Baileys only). `from` may be an `@lid` privacy id on either engine; resolve it with `GET /api/sessions/:sessionId/contacts/:contactId/phone` |-| `call.accepted` / `call.rejected` / `call.missed` | A ringing call ended, whether answered, declined, or never picked up. **Baileys only**: whatsapp-web.js emits no call-outcome event | `{ sessionId, callId, from, outcome, isVideo, isGroup, timestamp }`. `callId` matches the `call.received` that preceded it, so the pair can be correlated. The engines report _what_ happened, never _who_ did it: an accept can come from any linked device. An outcome is only sent for a call this session saw ring, and offline-replayed signalling for calls that ended while disconnected is dropped. WhatsApp's `terminate` is deliberately unmapped: it covers both a caller hanging up before answer and either side ending an answered call, with nothing to tell them apart |-| `status.received` | A contact posts a status/story (opt-in — see below) | `{ sessionId, statusId, contact: { id, name?, pushName? }, type, caption?, hasMedia, mediaOmitted, omitReason?, postedAt, expiresAt }` — `statusId` is the store's `id` (usable with the status endpoints below); `postedAt`/`expiresAt` are epoch **milliseconds** (unlike the epoch-seconds convention for message timestamps), matching the `GET /status` store's own `Date`-backed fields |+| Event | When it fires | `data` payload sketch |+| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `message.received` | An inbound message arrives | The full message object: `id`, `from`, `to`, `body`, `type`, `timestamp` (epoch **seconds**), `isGroup`, `kind` (user-facing chat discriminator of `chatId` — `individual\|group\|channel\|status\|broadcast\|unknown`), `fromMe`, `chatId`, `media{mimetype,filename?,data?,omitted?,sizeBytes?}` (media messages only), `contact{…}` (plus optional `senderPhone` for `@lid` senders, `order{orderId,token?}` / `product{productId,…}` on `order` / `product` messages, `poll{name,options,allowMultipleAnswers}` on a poll creation message, `buttons:[{id,text}]` on a WhatsApp Business prompt that offers choices, and `button{id,text?}` when the sender tapped one; **Baileys only**) |+| `message.sent` | An outbound message is created/sent from this session | Same message object shape as `message.received` |+| `message.ack` | A delivery/read receipt updates an outbound message. On Baileys only 1:1 receipts arrive: it reports group and status receipts per participant, which are not consumed, so an own group or status message stays at `sent`, see below | `{ id, messageId, status, ack, chatId? }` — `status` is the canonical state (`pending`/`sent`/`delivered`/`read`/`failed`); `ack` is the deprecated legacy integer derived from it; `chatId` is the conversation the acked message belongs to, present whenever the engine's update names the chat (both engines do on the live path) |+| `message.failed` | A receipt resolves to `failed` (dispatched in addition to `message.ack`) | `{ id, messageId, status: "failed", ack: -1, chatId? }`; `chatId` follows the same rules as `message.ack` |+| `message.revoked` | A message is deleted/recalled | `{ id, revokedId?, chatId, from, to, type: "revoked", body: "", timestamp }` — **reconcile on `revokedId`** (the original deleted message's id), falling back to `id`. On whatsapp-web.js `id` is the _revocation notification_ (a distinct message that won't match a stored id) and `revokedId` may be absent when the original isn't cached locally; on Baileys the two coincide |+| `message.reaction` | A reaction is added, changed, or removed | `{ messageId, chatId, reaction, senderId, reactions? }` — `reactions` is the post-apply `{ senderId: emoji }` snapshot, omitted when the gateway holds no stored copy of the message to compute it from (an ephemeral message, or one predating the session going live); treat it as unknown rather than empty and keep the map you already hold. `reaction` is empty when removed |+| `message.edited` | A message body or media caption is edited | `{ messageId, chatId, body, senderId, from, to, fromMe, isGroup, type, hasMedia, author?, mentionedIds?, timestamp }` — `messageId` is the original message id, `body` is the latest text/caption, and `timestamp` is the edit occurrence time in epoch **seconds** (not the original creation time) |+| `session.qr` | A new pairing QR is generated | `{ sessionId, qr }` — `qr` is a **PNG data URL** (`data:image/png;base64,…`), the same rendered value `GET /api/sessions/{sessionId}/qr` returns as `qrCode`, not the raw `2@…` linking ref. Render it directly in an `<img src>`; the raw ref never leaves the engine adapter |+| `session.authenticated` | The session pairs and becomes ready | `{ sessionId, phone, pushName }` |+| `session.disconnected` | The session disconnects on the engine or WhatsApp side (drop, conflict, or a phone-initiated unlink). Not fired for API-initiated stop/logout/delete — those are acknowledged by the API response and the `session.status` transition | `{ sessionId, reason }` |+| `session.reconnect_loop` | Every 5th consecutive reconnect attempt is scheduled (attempt 5, 10, 15, …) — the session is failing to come back up | `{ sessionId, attempts, nextDelayMs }` |+| `presence.update` | A subscribed chat's presence changed — someone came online, started typing, or stopped. Only actual CHANGES are dispatched: WhatsApp repeats itself freely, and every repeat would otherwise be a delivery | `{ sessionId, chatId, participants: [{ id, state, lastSeen? }], groupOnlineCount? }` — `state` is `available`/`unavailable`/`composing`/`recording`/`paused`; `lastSeen` is epoch **seconds** and absent when the contact hides it. Requires `POST .../presence/subscribe` first, and Baileys — whatsapp-web.js cannot observe presence |+| `event.response` | A guest answered a WhatsApp event invitation (going, not going, maybe). **Baileys only**; see the payload note below | `{ sessionId, eventMessageId, chatId, responderId, contact?, fromMe, response, extraGuestCount?, eventName?, responseMessageId, timestamp }`. `response` is `going`/`not_going`/`maybe`/`unknown`; `timestamp` is epoch **seconds** on the guest's clock. Order a guest's answers by `timestamp`, not by delivery |+| `session.restriction` | WhatsApp places a restriction on the account, or lifts one. Deduped: an unchanged restriction is not re-announced, and a lift is only sent when one was in force | `{ sessionId, active, kind, code, expiresAt }` — `active` is `false` for a lift and `kind`/`code` then describe the restriction that ended; `expiresAt` is an ISO timestamp or `null`. See `restriction` on the session response for the `kind` values |+| `session.status` | The session status transitions | `{ sessionId, status }` where `status` is one of `created` / `initializing` / `qr_ready` / `authenticating` / `ready` / `disconnected` / `action_required` / `failed` |+| `group.join` | Participant(s) are added to or join a group this session is in | `{ groupId, actorId?, participantIds, timestamp }`. `actorId` is the admin/inviter when known. **Baileys**: a session added to or joining a group reports only its own id in `participantIds` (members added with it are not listed) |+| `group.leave` | Participant(s) leave or are removed from a group | `{ groupId, actorId?, participantIds, timestamp }` |+| `group.update` | Group metadata changes (subject, description, announce/locked settings) | `{ groupId, actorId?, participantIds, changes?, timestamp }` — `changes` carries only the fields that changed: `subject?`, `description?`, `announce?`, `locked?` |+| `group.join_request` | Someone asked to join a group this session administers (join-approval mode on) | `{ groupId, actorId?, participantIds, timestamp }` — `participantIds` are the users asking to join; `actorId` is who created the request when the engine reports one (differs from the requester on a non-admin add). Act on it via `GET/POST .../groups/:groupId/membership-requests[...]` **Baileys caveat**: the library (7.0.0-rc14) emits this only for non-admin-add requests — an invite-link self-request may produce no event there (upstream TODO); the membership-requests list endpoint still reports it. |+| `call.received` | An incoming voice/video call starts ringing. Dispatched by both engines, but **not reliable on whatsapp-web.js**: it fired in a live test on 2026-09-17 and did not in one on 2026-08-10 | `{ callId, from, isVideo, isGroup, timestamp }` — `callId` is the id to pass to `POST /sessions/:sessionId/calls/:callId/reject` (Baileys only). `from` may be an `@lid` privacy id on either engine; resolve it with `GET /api/sessions/:sessionId/contacts/:contactId/phone` |+| `call.accepted` / `call.rejected` / `call.missed` | A ringing call ended, whether answered, declined, or never picked up. **Baileys only**: whatsapp-web.js emits no call-outcome event | `{ sessionId, callId, from, outcome, isVideo, isGroup, timestamp }`. `callId` matches the `call.received` that preceded it, so the pair can be correlated. The engines report _what_ happened, never _who_ did it: an accept can come from any linked device. An outcome is only sent for a call this session saw ring, and offline-replayed signalling for calls that ended while disconnected is dropped. WhatsApp's `terminate` is deliberately unmapped: it covers both a caller hanging up before answer and either side ending an answered call, with nothing to tell them apart |+| `status.received` | A contact posts a status/story (opt-in — see below) | `{ sessionId, statusId, contact: { id, name?, pushName? }, type, caption?, hasMedia, mediaOmitted, omitReason?, postedAt, expiresAt }` — `statusId` is the store's `id` (usable with the status endpoints below); `postedAt`/`expiresAt` are epoch **milliseconds** (unlike the epoch-seconds convention for message timestamps), matching the `GET /status` store's own `Date`-backed fields |> **`message.ack` on Baileys.** An own group or status message stays at `sent` unless the server rejects it, which still arrives as `failed`. The event is not limited to outbound messages: when the account's own phone reads a 1:1 chat, the messages received there are acked as `read` too, with no `fromMe` in the payload, and their stored copy moves to `read`.diff --git a/docs/17-dashboard-design.md b/docs/17-dashboard-design.mdindex 110fa435b..5ab0c696d 100644--- a/docs/17-dashboard-design.md+++ b/docs/17-dashboard-design.md@@ -491,8 +491,10 @@ The client lives in `src/services/api.ts`. A single `request<T>()` helper attachheader from `sessionStorage`, then returns **the parsed JSON body as-is** — the backend sends theraw handler payload, so `request<Session[]>('/sessions')` resolves to a bare `Session[]`, not`{ data: Session[] }`. (A `204 No Content` resolves to `undefined`; a `401`, or a `403` because the-key's `allowedIps` refuse this client, clears the stored key and redirects to login; any other `403`-leaves the key in place.) Endpoints are grouped into typed namespaces — `sessionApi`, `webhookApi`,+key's `allowedIps` refuse this client, clears the stored key and redirects to login, but only when the+stored key is the one the request carried: a late answer for a key since replaced fails like any other+error, and a keyless request answered after sign-out stays silent. Any other `403` leaves the key in+place.) Endpoints are grouped into typed namespaces — `sessionApi`, `webhookApi`,`templateApi`, `apiKeyApi`, `auditApi`, `messageApi`, `infraApi`, `pluginsApi`, `statsApi`, ...```typescriptdiff --git a/docs/26-global-search.md b/docs/26-global-search.mdindex 1b7bc1011..9ab27d083 100644--- a/docs/26-global-search.md+++ b/docs/26-global-search.md@@ -134,7 +134,7 @@ GET /api/search?q=<term>&sessionId=<id>&chatId=<id>&direction=<incoming|outgoing```- **`q`** is required and must be non-empty (whitespace-only is rejected with `400`, and so is one- longer than 1000 characters or with more than 32 words, punctuation separating words as whitespace does and each symbol or emoji counting as one; a repeated word counts once). Numeric params+ longer than 1000 characters or with more than 32 words, punctuation separating words as whitespace does and each symbol or emoji counting as one; a whitespace-separated word said again counts once). Numeric paramsare coerced and validated; a non-numeric `limit`/`offset`/`dateFrom`/`dateTo` surfaces as `400`,never as a `NaN` SQL parameter.- **Auth scoping is authoritative.** The caller's API-key `allowedSessions` is injected by