Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs: correct API reference, FAQ and dashboard design claims
Yudhi Armyndharis6fb5ee16d78e
diff --git a/.env.example b/.env.exampleindex 2769482e0..f9cc5d70d 100644--- a/.env.example+++ b/.env.example@@ -205,8 +205,9 @@ OPENWA_PIDS_LIMIT=2048# NOTE: the Baileys engine is loaded lazily (dynamic import, only when ENGINE_TYPE=baileys) and adds no# Node.js floor of its own; the package floor is Node.js 22.19 (engines.node).# BAILEYS_AUTH_DIR=./data/baileys-# NOTE: proxy egress is configured PER SESSION, on both engines, via the proxyUrl/proxyType fields on+# NOTE: proxy egress is configured PER SESSION, on both engines, via the proxyUrl field on# POST /api/sessions or PATCH /api/sessions/:sessionId/proxy (ADMIN), NOT via environment variables.+# The URL scheme (http, https, socks4, socks5) selects the protocol.# Pull the FULL message-history archive when the device is linked (large; set before linking, an# already-linked session must be re-linked). Off by default: the engine still enables the initial# sync (contacts, chats, recent messages, lid mappings) without downloading the entire history.@@ -930,8 +931,10 @@ PLUGINS_DIR=./data/plugins # Plugin directory (default: ./data/plugins)# BODY_SIZE_LIMIT=25mb # Max request body size (base64 media sends ride in the JSON body)# Aggregate cap on request-body bytes buffered across ALL connections. Once exceeded, new requests# get 503 + Retry-After without their body being read (protects against slow-body memory pinning).-# Keep it >= BODY_SIZE_LIMIT. Default: 4 x BODY_SIZE_LIMIT (100 MiB with the default 25mb cap).-# Below 2 x BODY_SIZE_LIMIT one full-size unkeyed body can leave no room for ingress deliveries.+# Keep it >= 2 x BODY_SIZE_LIMIT: an API key may hold at most half of it, so below that a full-size+# body sent with a key is refused with 413. Default: 4 x BODY_SIZE_LIMIT (100 MiB with the default+# 25mb cap). Below 3 x, unkeyed traffic at its pool limit leaves keyed requests less than one+# full-size body; below 2 x, one full-size unkeyed body can leave no room for ingress deliveries.# Requests without an active API key (ingress webhooks, unauthenticated callers) share a quarter of# it (at least two BODY_SIZE_LIMIT); the rest is kept for keyed requests. Each API key may hold at# most HALF of the budget, and each unkeyed client IP half of the unkeyed pool (or onediff --git a/docs/06-api-specification.md b/docs/06-api-specification.mdindex f3874c59d..558987164 100644--- a/docs/06-api-specification.md+++ b/docs/06-api-specification.md@@ -118,7 +118,7 @@ Validation failures (`statusCode: 400`) return `message` as an **array** of fiel| `403` | Forbidden | A valid key refused by its `allowedIps` (a blocked or undeterminable source IP) or used outside its `allowedSessions` scope, a key whose **role** is below the route's `@RequireRole` requirement, or a key with `allowedChats` that calls a route that is not chat-scoped, names a chat outside its allowlist, or sends a `quotedMessageId` outside the reply route (see Roles & Authorization) || `404` | Not Found | The addressed resource (session, message, webhook, batch, …) does not exist || `409` | Conflict | A uniqueness constraint was violated (e.g. duplicate name); a credential teardown for the same session name is still in flight on `start`/`delete` (retryable; body carries `code: 'SESSION_NAME_TEARDOWN_PENDING'`); or, on routes that reach a WhatsApp engine, the engine exists but is not ready yet (retryable; each route section carries the exact wording); or, on a multi-node deployment, another node currently owns the session's live engine (retryable) |-| `413` | Payload Too Large | The request body exceeds `BODY_SIZE_LIMIT`, or base64 or downloaded media exceeds the media byte cap (see §6.3) |+| `413` | Payload Too Large | The request body exceeds `BODY_SIZE_LIMIT`, or base64 or downloaded media exceeds the media byte cap (see §6.3), or the declared `Content-Length` is larger than the in-flight body budget, or the caller's share of it, could ever admit (not retryable, no `Retry-After`) || `415` | Unsupported Media | The request has a body carrying a `Content-Encoding` other than `identity`; compressed request bodies are not accepted, as the aggregate body cap counts wire bytes || `429` | Too Many Requests | A rate limit was exceeded: the per-client-IP tiers, the ingress per-instance limit, the concurrent bulk batch cap, or send pacing (body carries `code: 'SEND_PACING_LIMITED'` and `retryAfterSeconds`); honor `Retry-After` when present || `500` | Internal Server Error | Send failed at the WhatsApp engine or an unexpected server error; when WhatsApp Web itself threw during a whatsapp-web.js send or status post, the body carries `code: 'ENGINE_PAGE_ERROR'`, `pageError` (`name`, `message`) and, when the page could read it, the WhatsApp Web `build` |@@ -4725,15 +4725,15 @@ Update a webhook. Partial — only fields present in the body are changed.**Request body** — `UpdateWebhookDto` (all fields optional; only fields where the value is not `undefined` are applied)-| Field | Type | Required | Constraints | Description |-| ---------- | ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |-| url | string | no | omit to skip (explicit `null` → `400`), `@IsUrl({ require_tld: false, require_protocol: true, protocols: ['http', 'https'] })`, `@MaxCodePoints(2048)`; re-runs the SSRF guard when provided → `400` if blocked. | New URL. |-| events | string[] | no | omit to skip (explicit `null` → `400`), `@IsArray`, `@ArrayMinSize(1)`, `@IsIn([...WEBHOOK_EVENTS, '*'], { each: true })` | Same allowed set as create (incl. `*`). |-| secret | string | no | `@IsOptional`, `@IsString`, `@MinLength(16)` (skipped for `""`, which clears it), `@MaxCodePoints(255)` | **Write-only.** An empty string is normalized to `null`, which disables HMAC. |-| headers | Record<string,string> | no | omit to skip (explicit `null` → `400`), `@IsHeaderMap()` (same constraints as create) | **Write-only.** Replaces existing headers wholesale when provided. |-| filters | WebhookFilters \| null | no | `@IsOptional`, `@IsValidWebhookFilters()` | Set to `null` or `{ conditions: [] }` to clear filters. |-| active | boolean | no | omit to skip (explicit `null` → `400`), `@IsBoolean` | Enable/disable the webhook. (Present only on update, not create.) |-| retryCount | number (int) | no | omit to skip (explicit `null` → `400`), `@IsInt`, `@Min(0)`, `@Max(5)` | Total delivery attempts per event, including the first. |+| Field | Type | Required | Constraints | Description |+| ---------- | ---------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |+| url | string | no | omit to skip (explicit `null` → `400`), `@IsUrl({ require_tld: false, require_protocol: true, protocols: ['http', 'https'] })`, `@MaxCodePoints(2048)`; re-runs the credential and SSRF checks only when it differs from the stored URL → `400` if blocked. | New URL. |+| events | string[] | no | omit to skip (explicit `null` → `400`), `@IsArray`, `@ArrayMinSize(1)`, `@IsIn([...WEBHOOK_EVENTS, '*'], { each: true })` | Same allowed set as create (incl. `*`). |+| secret | string | no | `@IsOptional`, `@IsString`, `@MinLength(16)` (skipped for `""`, which clears it), `@MaxCodePoints(255)` | **Write-only.** An empty string is normalized to `null`, which disables HMAC. |+| headers | Record<string,string> | no | omit to skip (explicit `null` → `400`), `@IsHeaderMap()` (same constraints as create) | **Write-only.** Replaces existing headers wholesale when provided. |+| filters | WebhookFilters \| null | no | `@IsOptional`, `@IsValidWebhookFilters()` | Set to `null` or `{ conditions: [] }` to clear filters. |+| active | boolean | no | omit to skip (explicit `null` → `400`), `@IsBoolean` | Enable/disable the webhook. (Present only on update, not create.) |+| retryCount | number (int) | no | omit to skip (explicit `null` → `400`), `@IsInt`, `@Min(0)`, `@Max(5)` | Total delivery attempts per event, including the first. |```json{@@ -6403,8 +6403,9 @@ Search messages across sessions (active search provider).}```-- `snippet` is an XSS-safe text excerpt with `<mark>`/`</mark>` highlight markers around the matched- term (both dialects emit the same markers). Render it as text, never as HTML.+- `snippet` is a text excerpt with `<mark>`/`</mark>` highlight markers around the matched term (both+ dialects emit the same markers). The body text inside it is not HTML-escaped: split on the literal+ markers and render each segment as text, never the raw snippet as HTML.- `total` is an exact count for pagination, computed lazily only when the returned page could be full.- `provider` names which backend answered (e.g. `builtin-fts`); it is the registered `SearchProvider`id, so it changes when a plugin backend is selected via `SEARCH_PROVIDER`.@@ -6966,7 +6967,7 @@ Live events are pushed as a **nested** envelope (note: `data` is under `payload`}```-Error `code` values include `UNAUTHORIZED`, `INVALID_MESSAGE`, `INVALID_SESSION`, `INVALID_EVENTS`, `FORBIDDEN_SESSION`, `TOO_MANY_SUBSCRIPTIONS`, and `RATE_LIMITED`. `RATE_LIMITED` is followed by a disconnect when a handshake exceeds the per-IP connection-attempt window or the key's concurrent-socket cap; a frame over the per-key frame budget gets `RATE_LIMITED` and is dropped undispatched, and the socket stays open. A subscribe answers `INVALID_SESSION` when `sessionId` is missing, or is neither `"*"` nor a session id of at most 128 letters, digits and hyphens. It answers `TOO_MANY_SUBSCRIPTIONS` when it would take the connection past 4096 rooms (one per session and event subscribed); unsubscribe before subscribing to more.+Error `code` values include `UNAUTHORIZED`, `INVALID_MESSAGE`, `INVALID_SESSION`, `INVALID_EVENTS`, `FORBIDDEN_SESSION`, `TOO_MANY_SUBSCRIPTIONS`, and `RATE_LIMITED`. `RATE_LIMITED` is followed by a disconnect when a handshake exceeds the per-IP connection-attempt window or the key's concurrent-socket cap; a frame over the per-key frame budget gets `RATE_LIMITED` and is dropped undispatched, and the socket stays open. A subscribe answers `INVALID_SESSION` when `sessionId` is missing, or is neither `"*"` nor a session id of at most 128 letters, digits and hyphens. An unsubscribe answers `INVALID_SESSION` when `sessionId` is missing, empty or not a string. A subscribe answers `TOO_MANY_SUBSCRIPTIONS` when it would take the connection past 4096 rooms (one per session and event subscribed); unsubscribe before subscribing to more.### Subscribable events@@ -7056,29 +7057,29 @@ 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`), `hasMedia`, `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 | `{ id, messageId, status, ack }` — `status` is the canonical state (`pending`/`sent`/`delivered`/`read`/`failed`); `ack` is the deprecated legacy integer derived from it |-| `message.failed` | A receipt resolves to `failed` (dispatched in addition to `message.ack`) | `{ id, messageId, status: "failed", ack: -1 }` |-| `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 |-| `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, `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 | `{ id, messageId, status, ack }` — `status` is the canonical state (`pending`/`sent`/`delivered`/`read`/`failed`); `ack` is the deprecated legacy integer derived from it |+| `message.failed` | A receipt resolves to `failed` (dispatched in addition to `message.ack`) | `{ id, messageId, status: "failed", ack: -1 }` |+| `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 |+| `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 |> **`status.received` is opt-in and carries no media blob.** Unlike every other event above, `status.received` is only delivered to a webhook whose `events` list explicitly includes `"status.received"` (or `"*"`) — registering for other events does not implicitly subscribe you to it. The payload never embeds media bytes: when `hasMedia` is `true`, fetch the file separately via `GET /api/sessions/:sessionId/status/:statusId/media`. Your own posted statuses never trigger this event — only inbound stories from contacts (an own-send echo is dropped before ingest).diff --git a/docs/12-troubleshooting-faq.md b/docs/12-troubleshooting-faq.mdindex 0e2bfe0de..0844486ac 100644--- a/docs/12-troubleshooting-faq.md+++ b/docs/12-troubleshooting-faq.md@@ -860,7 +860,8 @@ BODY_SIZE_LIMIT=25mb# Note: one active API key may hold at most half the aggregate in-flight budget, wherever its# requests come from, and is refused with 503 + Retry-After past that even while the gateway as a-# whole has room. Requests without a recognised key (ingress deliveries included) share a pool of a+# whole has room. A single declared body larger than that share gets 413 instead, since a retry+# cannot help. Requests without a recognised key (ingress deliveries included) share a pool of a# quarter of the budget or twice BODY_SIZE_LIMIT, whichever is larger, and each client IP gets at# most half of that pool (never less than one full-size body). Behind a reverse proxy, set# TRUSTED_PROXIES: without it every unkeyed caller resolves to the proxy's own address and sharesdiff --git a/docs/17-dashboard-design.md b/docs/17-dashboard-design.mdindex f48e0e5af..74709e701 100644--- a/docs/17-dashboard-design.md+++ b/docs/17-dashboard-design.md@@ -61,7 +61,7 @@ backed by `localStorage` — there is no Zustand store.originals, which are 6:1 or better on the dark surfaces, and lightens error to `#f15e5e` becausethe original measures 4.06:1 there.Known gap: the exclusive button groups report `aria-pressed` without arrow-key roving focus. Every- page except Login has a render test, but only Infrastructure's resolves the caption references+ page has a render test, but only Infrastructure's resolves the caption referencesagainst a real DOM; elsewhere they are checked structurally. Treat the claim as directional, notcertified.5. **Dark mode** - Support for light/dark themes@@ -390,22 +390,22 @@ no DOM. Nothing under `chats/` ships its own stylesheet either: those componentsfrom `pages/Chats.css`, and `MediaLightbox` adds the `yet-another-react-lightbox` vendor CSS. Thereis no design-system package to pull from.-| Component | File | Responsibility |-| ---------------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------- |-| `Layout` | `components/Layout.tsx` | App shell: collapsible sidebar nav, mobile drawer, language menu, light/dark theme toggle, logout, live version badge |-| `ToastProvider` / `useToast` | `components/Toast.tsx` | Context-based toast notifications (success/error/warning/info) with de-dup keys |-| `PageHeader` | `components/PageHeader.tsx` | Shared page title / subtitle / badge / actions header |-| `Modal` | `components/Modal.tsx` | Accessible dialog (`role="dialog"`, Escape/overlay close, focus trap + restore); uses the global `.modal-*` styles |-| `CustomSelect` | `components/CustomSelect.tsx` | Keyboard-navigable select replacement (type-ahead, arrow keys) used by Sessions / Logs / Login |-| `DashboardCharts` | `components/DashboardCharts.tsx` | `recharts`-based message-volume / activity charts on the Dashboard |-| `FilterBuilder` | `components/FilterBuilder.tsx` | Visual condition builder for webhook event filters |-| `GlobalSearch` | `components/GlobalSearch.tsx` | Debounced message-search box in the Chats header, with all-sessions / current-session scope |-| `PluginInstances` | `components/PluginInstances.tsx` | Per-plugin instance list: create / edit / delete and secret regeneration |-| `ErrorBoundary` | `components/ErrorBoundary.tsx` | Top-level React error boundary wrapping the whole app |-| `GithubIcon` | `components/GithubIcon.tsx` | Inline brand SVG |-| `GroupPicker` | `components/GroupPicker.tsx` | Searchable multi-select of a session's groups, used by the Message Tester's multi-group send |-| `SessionScopePicker` | `components/SessionScopePicker.tsx` | Per-key session scope checklist on the API Keys page |-| `RoleProvider` | `components/RoleProvider.tsx` | Context holding the logged-in key's role, read with `useRole` (`canWrite` gates write actions) |+| Component | File | Responsibility |+| ---------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |+| `Layout` | `components/Layout.tsx` | App shell: collapsible sidebar nav, mobile drawer, language menu, light/dark/system theme toggle, logout, live version badge |+| `ToastProvider` / `useToast` | `components/Toast.tsx` | Context-based toast notifications (success/error/warning/info) with de-dup keys |+| `PageHeader` | `components/PageHeader.tsx` | Shared page title / subtitle / badge / actions header |+| `Modal` | `components/Modal.tsx` | Accessible dialog (`role="dialog"`, Escape/overlay close, focus trap + restore); uses the global `.modal-*` styles |+| `CustomSelect` | `components/CustomSelect.tsx` | Keyboard-navigable select replacement (type-ahead, arrow keys) used by Sessions / Logs / Login |+| `DashboardCharts` | `components/DashboardCharts.tsx` | `recharts`-based message-volume / activity charts on the Dashboard |+| `FilterBuilder` | `components/FilterBuilder.tsx` | Visual condition builder for webhook event filters |+| `GlobalSearch` | `components/GlobalSearch.tsx` | Debounced message-search box in the Chats header, with all-sessions / current-session scope |+| `PluginInstances` | `components/PluginInstances.tsx` | Per-plugin instance list: create / edit / delete and secret regeneration |+| `ErrorBoundary` | `components/ErrorBoundary.tsx` | Top-level React error boundary wrapping the whole app |+| `GithubIcon` | `components/GithubIcon.tsx` | Inline brand SVG |+| `GroupPicker` | `components/GroupPicker.tsx` | Searchable multi-select of a session's groups, used by the Message Tester's multi-group send |+| `SessionScopePicker` | `components/SessionScopePicker.tsx` | Per-key session scope checklist on the API Keys page |+| `RoleProvider` | `components/RoleProvider.tsx` | Context holding the logged-in key's role, read with `useRole` (`canWrite` gates write actions) |Chat-specific pieces live one level down in `components/chats/`: `MessageBody` (WhatsApp textformatting + link detection), `ChatThread` (bubble list, including inbound Baileys prompt buttons@@ -661,7 +661,8 @@ that toggles one attribute on `<html>` and lets the CSS do the rest. The value i- **Mode** — `light | dark | system`. `system` removes `data-theme` so a `prefers-color-scheme`media query in the global CSS takes over; otherwise `data-theme="light|dark"` is set explicitly.-The sidebar footer button toggles light ↔ dark directly (resolving `system` first); there is no+The sidebar footer button cycles light → dark → system, its label naming the mode a click+selects; there is nopicker popover and no `ThemeProvider` context wrapper — it's a hook consumed directly where needed.An earlier accent-palette picker (seven palettes via `data-palette`) was removed formaintainability; the legacy `openwa_palette` storage key and the attribute are cleaned up on load.