Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(media): clarify archive recovery behavior
Yudhi Armyndharis2383d61cb27d
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 65dcb572d..6fb92e23c 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -17,6 +17,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0### Fixed+- Preserve archived media and reactions during concurrent metadata updates.+- Keep sent media when merging onto an echo row fails.+- Keep inline media when its WhatsApp message ID is unavailable.+- Enforce chat media size limits using decoded payload bytes.+- Bound archived dashboard previews alongside inline media.+- Preserve the Java failure constructor and empty Go redrive filters.- Keep narrow chat panes scrollable and prevent message actions from shrinking previews.- Open archived images in the dashboard media viewer without fetching them again.- Forward container shutdown signals after dropping process privileges in Compose and Helm.diff --git a/docs/06-api-specification.md b/docs/06-api-specification.mdindex 307ae025f..d502a70f0 100644--- a/docs/06-api-specification.md+++ b/docs/06-api-specification.md@@ -1353,7 +1353,7 @@ Get persisted message history for a session from the local DB (paginated, filterEach `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) }`. 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).-> **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 `createdAt` DESC order above, 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).+> **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 `createdAt` DESC order above, 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).**Errors:** `400` `after` names no message in this session · `401` missing/invalid API key · `403` a key restricted to selected chats sent no `chatId`, or one outside its allowlist@@ -1560,16 +1560,18 @@ copy: the row keeps its inline base64 too. Setting `MESSAGE_INLINE_MEDIA=archive`CHAT_MEDIA_ARCHIVE_ENABLED=true`; the boot fails otherwise) stores each archived file once: afterthe file is written, read back byte for byte and the row points at it, the row's`metadata.media` is replaced with `{ mimetype, filename?, omitted: true, sizeBytes, archived: true }`,-and this route becomes the only way to the bytes. Any failure along the way (a store that does not-read back intact, a row revoked or re-pointed meanwhile) keeps the inline copy, so the mode can miss-a saving but not lose media. What it does not cover: media over `CHAT_MEDIA_ARCHIVE_MAX_BYTES` is-not archived and stays inline; outbound media is archived (and replaced) only with+and this route becomes the only way to the bytes. Storage or verification failures leave the inline+copy intact. Concurrent row updates are preserved, and a revoked message stays revoked.+What it does not cover: media over `CHAT_MEDIA_ARCHIVE_MAX_BYTES` is+not archived and stays inline; a row without a WhatsApp message ID keeps its inline bytes;+outbound media is archived (and replaced) only with`CHAT_MEDIA_ARCHIVE_OUTBOUND=true`; rows stored before the switch keep their inline copy. Twoconsequences to weigh before enabling it: with a non-zero `CHAT_MEDIA_ARCHIVE_TTL_DAYS`, retentionnow removes the only copy, after which this route answers `404`; and a database export no longercarries those bytes, so back up the media store alongside the database. Webhook payloads carry thein-memory engine message rather than the row, so they are unaffected. The dashboard previews-archived images, video and audio inline by fetching them from this route.+archived images, video and audio inline by fetching them from this route. The latest 100 inline or+archived previews share a memory cap; older media keeps its download button.A revoked message (deleted for everyone, or through `POST /messages/delete`) has no media: its row iscleared on revoke, and this route answers `404` for it.@@ -4719,6 +4721,9 @@ Replay recorded webhook deliveries that still hold their event data, in one bounEach replay reuses the row's stored `idempotencyKey` (sent as `X-OpenWA-Idempotency-Key`), so receivers can deduplicate a POST that timed out after processing. `webhook:before` hooks run again on the stored pre-hook data. Each row gets **one direct POST** inside the request, including when ordinary dispatch uses the queue. Success removes its row; another failure keeps it and raises its attempt count. Calls on one node run serially. The audit log records counts without payload content.+Choose a batch limit that fits the client's timeout, especially for unavailable receivers. A client+timeout does not cancel the batch; inspect the failure log before retrying it.+**Auth:** API key (ADMIN) · **Scope:** rows are confined to the calling key's `allowedSessions`; the body's `sessionId` can only narrow that. A row is replayed only to the webhook it was recorded for, and only while that webhook still belongs to the row's session.**Request body** (every field optional; an empty body `{}` takes the eligible rows with the fewest attempts)