Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs: add the missing upgrade notes and recipient-lookup errors
Yudhi Armyndharis26a0c35dad72
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 446e2bf98..e5623613f 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -48,7 +48,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- Stop a request left over from before logout from reloading the dashboard login form.- Stop a dashboard Logs export from downloading rows after sign-out when its last page was throttled.- Stop reopening a just-saved dashboard template from loading its old values, which a second save wrote back.-- Stop an operator webhook redrive at its next row on shutdown.- Stop an operator ingress dead-letter redrive at its next row on shutdown, leaving the rows it did not reach unchanged.- Run a plugin's `onDisable` once when shutdown, uninstall or an update overlaps a disable already in progress.- Answer `503` and keep the previous version when shutdown begins before an update of a plugin the operator switched on has applied.@@ -57,8 +56,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- Leave a session start that shutdown interrupts for the next boot instead of marking it failed.- Destroy session engines at shutdown before waiting on a boot auto-start launch, and bound that wait, so a stalled launch no longer holds teardown past the kill deadline.- Stop taking ingress queue jobs once shutdown begins after SIGTERM, SIGINT or an admin restart, instead of running them against stopped sessions.-- Run the daily ingress retention hand-off after a reconcile sweep in progress instead of skipping it.-- Try each failing ingress retention hand-off row once per run instead of stopping at the first batch of them.- Retire the ingress replay sweep's duplicate dead letter when it races another dead-letter write, and stop logging an event a redrive delivered meanwhile as dead-lettered.- Fall back instead of hanging when an ingress, webhook or infra status queue call runs before Redis has ever connected.- Drop whatsapp-web.js inbound media over `MEDIA_DOWNLOAD_MAX_BYTES` in the page when the sender understates its size.@@ -78,7 +75,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- Close queue workers, waiting up to 10 s for running jobs, before plugins shut down, so no new job is taken against stopped plugins.- Answer new HTTP requests other than health probes with `503` once teardown begins after SIGTERM, SIGINT or `POST /api/infra/restart`; a Socket.IO handshake is still admitted until the server closes.- Disable plugins in parallel at shutdown, capping the whole plugin phase, including waits for enables in progress, at 10 s.-- Bound the webhook redrive wait at shutdown by `WEBHOOK_SHUTDOWN_DRAIN_MS`, like the delivery drain and reconciler.- Exit with status 1 when teardown runs 67 s past the shutdown delay, so a stalled close no longer runs into the kill deadline or hangs `POST /api/infra/restart`.- Destroy open HTTP connections and WebSocket clients when the server closes at shutdown, so an open request cannot hold up the database close.- Stop waiting for a queue worker whose close outlasts its 10 s cap, so it cannot hold up the database close.@@ -96,15 +92,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- Dead-letter undispatched ingress events instead of deleting them when they age out of the dedup window.- Keep a re-sent ingress delivery redrivable when an earlier dead letter for its id was already redriven.- Deliver Baileys API edit and revoke events to webhook and WebSocket consumers.-- Preserve chat-scoped WebSocket event order while resolving chat identities.- Emit Baileys API reaction updates, including reaction removal.-- Restore legacy webhook failures and normalize terminal duplicates before SQLite schema synchronization.-- Exclude retained webhook replay payloads from database backup reads.-- Advance webhook recovery scans past live queued deliveries.- Apply current receiver configuration and session ownership to every webhook delivery attempt.- Clear revoked Baileys history messages from storage, previews, quoted replies, and plugin indexes.- Preserve pending message mutations when REST storage wins an own-send echo.-- Cancel archived media preview downloads when their components unmount.- Refresh Baileys pairing secrets and prevent stale QR renders during linking.- Upgrade proxy-addr to 2.0.8 (GHSA-jqcg-44mw-7w3h, critical) to correct IPv4-mapped IPv6 proxy trust matching.- Upgrade source-map-js to 1.2.2 to validate indexed source-map offsets.@@ -113,10 +104,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- Keep sent media when merging onto an echo row fails.- Enforce chat media size limits using decoded payload bytes.- 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.- Preserve webhook outbox payloads until delivery or durable failure storage succeeds.-- Enforce webhook replay retention and keep later eligible failures moving through batches.- Keep one terminal webhook failure per receiver idempotency key.- Reject poll votes with no matching options while preserving explicit vote clearing.@@ -159,6 +148,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- New Baileys pairings show `Ubuntu` instead of `OpenWA` as the device name in Linked Devices; set `BAILEYS_BROWSER_NAME=OpenWA` to keep the old name. Linked sessions are unaffected.- `backup.sh` and `restore.sh` exit with status 2 when `./.env` or `.env.generated` sets a key in a form they cannot parse; fix the line or pass the key in the environment.- With `DATABASE_SSL=true`, `backup.sh` now fails against a PostgreSQL server whose certificate the app would reject; trust a private CA through `NODE_EXTRA_CA_CERTS` or `PGSSLROOTCERT`, and give `DATABASE_URL` the host name the certificate carries or set `PGSSLMODE`.+- Baileys answers `400` for a phone number WhatsApp reports as unregistered, where it answered `201`, and `503` when the recipient lookup gets no answer; every send to a phone number without a known LID now makes one lookup first.+- `vote-poll` on whatsapp-web.js answers `400` `POLL_OPTION_NOT_FOUND` when none of the option texts match, where it answered `200` and cleared the vote; an empty `options` list still clears it.+- Once teardown begins, every request except `/api/health` and `/api/health/*` answers `503` with `Connection: close`, `GET /api/infra/health` included; probe `/api/health/live` for a check that survives teardown.+- A compose file or pod spec of your own that drops all capabilities must add `KILL` to the shipped five, or a stop never reaches the app: it runs out the grace period and exits `137`.+- Rolling back to 0.24.0 while webhook outbox rows are in state `queued` strands them: 0.24.0 never replays that state and prunes it after `WEBHOOK_OUTBOX_RETENTION_DAYS` (default 7). The upgrade also deletes duplicate terminal `webhook_delivery_failures` rows, which a rollback does not restore.## [0.24.0] - 2026-10-03diff --git a/docs/06-api-specification.md b/docs/06-api-specification.mdindex c6d3a0716..e8e7f8958 100644--- a/docs/06-api-specification.md+++ b/docs/06-api-specification.md@@ -1514,7 +1514,7 @@ Pin a message in its chat for a bounded window.**Response** `200` — `{ "success": true }`-**Errors:** `400` session not active, or `durationSeconds` outside the three accepted values · `401` missing/invalid API key · `403` the whatsapp-web.js engine refused the pin (in a group only admins may pin; the Baileys engine has no acceptance signal and answers `200`) · `404` message not found in the chat · `409` conflict or engine not ready (retryable) · `503` the whatsapp-web.js page died mid-request; a retry is safe but restarts the pin duration+**Errors:** `400` session not active, or `durationSeconds` outside the three accepted values · `401` missing/invalid API key · `403` the whatsapp-web.js engine refused the pin (in a group only admins may pin; the Baileys engine has no acceptance signal and answers `200`) · `404` message not found in the chat · `409` conflict or engine not ready (retryable) · `503` the whatsapp-web.js page died mid-request; a retry is safe but restarts the pin duration; on Baileys, also when the recipient lookup failed or timed out before the operation was sent (nothing reached WhatsApp, so a retry is safe)> On whatsapp-web.js the message must be within the 100-message fetch window for the chat, the same> limit that applies to react/delete/edit. On Baileys it must be in the adapter's message store.@@ -1558,7 +1558,7 @@ Remove a message's pin. Takes no duration.**Response** `200` — `{ "success": true }`-**Errors:** `400` session not active · `401` missing/invalid API key · `403` the whatsapp-web.js engine refused the unpin (in a group only admins may unpin; the Baileys engine has no acceptance signal and answers `200`) · `404` message not found in the chat · `409` conflict or engine not ready (retryable) · `503` the whatsapp-web.js page died mid-request; repeating it is safe (retryable)+**Errors:** `400` session not active · `401` missing/invalid API key · `403` the whatsapp-web.js engine refused the unpin (in a group only admins may unpin; the Baileys engine has no acceptance signal and answers `200`) · `404` message not found in the chat · `409` conflict or engine not ready (retryable) · `503` the whatsapp-web.js page died mid-request; repeating it is safe (retryable); on Baileys, also when the recipient lookup failed or timed out before the operation was sent (nothing reached WhatsApp, so a retry is safe)#### GET /api/sessions/:sessionId/messages/:chatId/:messageId/media@@ -1933,7 +1933,7 @@ Send an image (by URL or base64) with an optional caption.{ "messageId": "[email protected]_3EB0ABCD", "timestamp": 1719312000 }```-**Errors:** `400` neither `url` nor `base64`, base64 without `mimetype`, SSRF-blocked URL, a `url` that answers non-2xx, times out or cannot be reached, session not active, or unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `413` base64 or downloaded media over the media cap (see §6.3) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable) · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends))+**Errors:** `400` neither `url` nor `base64`, base64 without `mimetype`, SSRF-blocked URL, a `url` that answers non-2xx, times out or cannot be reached, session not active, or unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `413` base64 or downloaded media over the media cap (see §6.3) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable); on Baileys, also when the recipient lookup failed or timed out before the operation was sent (nothing reached WhatsApp, so a retry is safe) · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends))#### POST /api/sessions/:sessionId/messages/send-video@@ -1959,7 +1959,7 @@ Send a video (by URL or base64) with an optional caption. Uses the same `SendMed{ "messageId": "[email protected]_3EB0ABCD", "timestamp": 1719312000 }```-**Errors:** `400` media validation failure / a `url` that answers non-2xx, times out or cannot be reached / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `413` base64 or downloaded media over the media cap (see §6.3) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable) · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends))+**Errors:** `400` media validation failure / a `url` that answers non-2xx, times out or cannot be reached / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `413` base64 or downloaded media over the media cap (see §6.3) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable); on Baileys, also when the recipient lookup failed or timed out before the operation was sent (nothing reached WhatsApp, so a retry is safe) · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends))#### POST /api/sessions/:sessionId/messages/send-audio@@ -1985,7 +1985,7 @@ Send an audio message (by URL or base64). Uses `SendAudioMessageDto`. A `caption{ "messageId": "[email protected]_3EB0ABCD", "timestamp": 1719312000 }```-**Errors:** `400` media validation failure / a `url` that answers non-2xx, times out or cannot be reached / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `413` base64 or downloaded media over the media cap (see §6.3) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable) · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends))+**Errors:** `400` media validation failure / a `url` that answers non-2xx, times out or cannot be reached / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `413` base64 or downloaded media over the media cap (see §6.3) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable); on Baileys, also when the recipient lookup failed or timed out before the operation was sent (nothing reached WhatsApp, so a retry is safe) · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends))#### POST /api/sessions/:sessionId/messages/send-document@@ -2018,7 +2018,7 @@ Send a document/file (by URL or base64). Uses `SendMediaMessageDto`; `filename`**Engine differences:** Baileys always sends a document as a document, while whatsapp-web.js deliberately keeps normal mimetype classification for `status@broadcast` and broadcast lists; the library returns `null` for document-mode sends to those recipients, so forcing the flag there would turn a working send into a failure. For URL-based sends without an explicit `filename`, whatsapp-web.js derives the URL basename, percent-decoded; Baileys falls back to the literal `file`.-**Errors:** `400` media validation failure / a `url` that answers non-2xx, times out or cannot be reached / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `413` base64 or downloaded media over the media cap (see §6.3) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable) · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends))+**Errors:** `400` media validation failure / a `url` that answers non-2xx, times out or cannot be reached / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `413` base64 or downloaded media over the media cap (see §6.3) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable); on Baileys, also when the recipient lookup failed or timed out before the operation was sent (nothing reached WhatsApp, so a retry is safe) · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends))#### POST /api/sessions/:sessionId/messages/send-location@@ -2118,7 +2118,7 @@ Send a sticker (by URL or base64; typically webp). Reuses `SendMediaMessageDto`.{ "messageId": "[email protected]_3EB0ABCD", "timestamp": 1719312000 }```-**Errors:** `400` media validation failure / (Baileys) media that is neither WebP nor an image that converts to one, or an animation with more than 500 frames / a `url` that answers non-2xx, times out or cannot be reached / session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `413` base64 or downloaded media over the media cap (see §6.3) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine, or (whatsapp-web.js) a sticker to a channel, `status@broadcast` or a broadcast list · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable) · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends))+**Errors:** `400` media validation failure / (Baileys) media that is neither WebP nor an image that converts to one, or an animation with more than 500 frames / a `url` that answers non-2xx, times out or cannot be reached / session not active / unknown body field; on Baileys, also a phone number WhatsApp reports as unregistered · `401` missing/invalid API key · `403` key role below OPERATOR · `404` the `quotedMessageId` could not be resolved (see Quoted sends) · `413` base64 or downloaded media over the media cap (see §6.3) · `500` engine error · `409` conflict or engine not ready (retryable) · `501` not supported on the active engine, or (whatsapp-web.js) a sticker to a channel, `status@broadcast` or a broadcast list · `503` a `url` fetch through the session's egress proxy failed before any response, the proxy or the target at fault (retryable); on Baileys, also when the recipient lookup failed or timed out before the operation was sent (nothing reached WhatsApp, so a retry is safe) · `422` the `Idempotency-Key` was already used for a different request (see [Idempotent sends](#idempotent-sends))#### POST /api/sessions/:sessionId/messages/send-poll@@ -2303,7 +2303,7 @@ The controller hardcodes the result after the engine call. Note the `200` status{ "success": true }```-**Errors:** `400` session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` message not found in this chat · `500` engine error · `409` conflict or engine not ready (retryable) · `503` the whatsapp-web.js page died mid-request; repeating it is safe (retryable)+**Errors:** `400` session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` message not found in this chat · `500` engine error · `409` conflict or engine not ready (retryable) · `503` the whatsapp-web.js page died mid-request; repeating it is safe (retryable); on Baileys, also when the recipient lookup failed or timed out before the operation was sent (nothing reached WhatsApp, so a retry is safe)#### POST /api/sessions/:sessionId/messages/delete@@ -2337,7 +2337,7 @@ After the engine delete, the stored message's body and `metadata` (inline media,{ "success": true }```-**Errors:** `400` session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` message not found in this chat · `500` engine error · `409` conflict or engine not ready (retryable) · `503` session not ready or dependency unavailable (retryable)+**Errors:** `400` session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR · `404` message not found in this chat · `500` engine error · `409` conflict or engine not ready (retryable) · `503` session not ready or dependency unavailable (retryable); on Baileys, also when the recipient lookup failed or timed out before the operation was sent (nothing reached WhatsApp, so a retry is safe)#### POST /api/sessions/:sessionId/messages/edit@@ -2372,7 +2372,7 @@ Both fields describe the edited message rather than the edit itself, on both eng{ "messageId": "[email protected]_3EB0ABCD", "timestamp": 1760000000 }```-**Errors:** `400` session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR, or the engine refused the edit (both engines refuse a message the account did not send; whatsapp-web.js also refuses one that is not text, where the Baileys engine has no acceptance signal and answers `200`) · `404` message not found · `409` conflict or engine not ready (retryable) · `503` the whatsapp-web.js page died mid-request; repeating it is safe (retryable)+**Errors:** `400` session not active / unknown body field · `401` missing/invalid API key · `403` key role below OPERATOR, or the engine refused the edit (both engines refuse a message the account did not send; whatsapp-web.js also refuses one that is not text, where the Baileys engine has no acceptance signal and answers `200`) · `404` message not found · `409` conflict or engine not ready (retryable) · `503` the whatsapp-web.js page died mid-request; repeating it is safe (retryable); on Baileys, also when the recipient lookup failed or timed out before the operation was sent (nothing reached WhatsApp, so a retry is safe)#### POST /api/sessions/:sessionId/messages/send-bulk@@ -3797,7 +3797,7 @@ Send a product message (catalog product card) to a chat. Note: this route lives**Response** `201` (Baileys engine only) — the sent `MessageResult`-**Errors:** `400` missing or empty `chatId`/`productId`, a `productId` over 255 or a `body` over 4096 characters, wrong types, any field not on the DTO, a product with no image (a product card needs one), or a `message:sending` plugin blocked the send or returned an invalid `productId`/`body` · `401` missing/invalid API key · `403` API-key role below OPERATOR, or WhatsApp refused the catalog query · `404` `Session <sessionId> not found or not connected`, or the product is not in the session catalog · `409` session present but not READY (retryable) · `500` engine error · `501` whatsapp-web.js only (no Catalog API) · `503` the catalog query went unanswered or was rate-limited by WhatsApp, or the session/dependency is not ready (a rate limit or the not-ready case can clear on retry; a silently unanswered catalog query does not)+**Errors:** `400` missing or empty `chatId`/`productId`, a `productId` over 255 or a `body` over 4096 characters, wrong types, any field not on the DTO, a product with no image (a product card needs one), or a `message:sending` plugin blocked the send or returned an invalid `productId`/`body`; on Baileys, also a phone number WhatsApp reports as unregistered · `401` missing/invalid API key · `403` API-key role below OPERATOR, or WhatsApp refused the catalog query · `404` `Session <sessionId> not found or not connected`, or the product is not in the session catalog · `409` session present but not READY (retryable) · `500` engine error · `501` whatsapp-web.js only (no Catalog API) · `503` the catalog query went unanswered or was rate-limited by WhatsApp, or the session/dependency is not ready (a rate limit or the not-ready case can clear on retry; a silently unanswered catalog query does not); on Baileys, also when the recipient lookup failed or timed out before the operation was sent (nothing reached WhatsApp, so a retry is safe)On whatsapp-web.js the readiness guard runs before the refusal, so a session that exists but is not`READY` gets `409` instead of `501`. Baileys resolves the product from the session catalog and sendsdiff --git a/docs/09-testing-strategy.md b/docs/09-testing-strategy.mdindex e90f98fca..2f0e9c89c 100644--- a/docs/09-testing-strategy.md+++ b/docs/09-testing-strategy.md@@ -263,7 +263,7 @@ request's superseded run; push runs on `main` are never cancelled or queued behi| `dashboard` | dashboard install, lint, formatting, type-check, i18n parity, build, unit tests || `scripts-smoke` | shellcheck on `docker-entrypoint.sh` and every `scripts/*.sh`, plus the backup/restore smoke test || `chart` | helm lint, helm template with default and fully-toggled values, kubeconform on both renders, the rendered-behaviour check, actionlint on the workflows |-| `build` | backend build after lint/audit/test/dashboard/scripts-smoke/chart jobs pass, then `test:engine-real`, which feeds proto-built inbound messages through the real Baileys library and the compiled adapter (every jest lane stubs Baileys) |+| `build` | backend build after lint/audit/test/dashboard/scripts-smoke/chart jobs pass, then `test:engine-real`, which feeds proto-built inbound messages and the outbound recipient preparation through the real Baileys library and the compiled adapter (every jest lane stubs Baileys) || `docker` | multi-arch build on pushes and pull requests, then against the built image `scripts/smoke-test-non-root.sh` (the entrypoint's root→openwa drop) and `scripts/smoke-test-engine-libs.sh` (imports Baileys and launches the browser, on the runner's native architecture only; the release workflow also runs it for linux/arm64 under emulation, where only the browser binary is executed). Publishes only on push: `:<sha>` from the build, then the branch tag (`:main`) once the smokes pass and only while the commit is still the branch head |SDK CI is defined in `.github/workflows/sdk-ci.yml` and is path-filtered to SDK sources plus server