Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs: correct four claims about routes, counts and the call hook
Yudhi Armyndharis5f7d74a7cb9c
diff --git a/.env.example b/.env.exampleindex 6f8c985a6..9cd30b50d 100644--- a/.env.example+++ b/.env.example@@ -480,7 +480,7 @@ WEBHOOK_SSRF_PROTECT=true# download holds memory up to MEDIA_DOWNLOAD_MAX_BYTES; this bounds N. Unset takes the default; a# value that is not a positive integer fails the boot.# INBOUND_MEDIA_CONCURRENCY=4 # default 4-# Fetch a caller-supplied URL (a media URL passed to a send or to POST /media/convert, and the link+# Fetch a caller-supplied URL (a media URL passed to a send or to POST /media/convert/voice|video, and the link# preview of a text send) through the egress proxy of the session the request names. ON by default,# so the destination sees the same address as the rest of that session's traffic. Set to false when# the proxy is a WhatsApp-only route that cannot reach arbitrary media hosts: those fetches thendiff --git a/CHANGELOG.md b/CHANGELOG.mdindex eb59d3b07..601bf1572 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -48,7 +48,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- An ingress route can declare `dedupOn: "body"` to key provider retries on the raw body instead of the delivery-id header. A provider that mints a fresh delivery id on every retry attempt, as supabase/auth does inside its hook retry loop, was never deduplicated when an ack was lost, so the contact received the message twice; routes that do not declare it keep the header ([#1641](https://github.com/rmyndharis/OpenWA/issues/1641)).- Baileys sessions record a message the account sent from its phone while the gateway was down, and dispatch `message.sent` for it, as they already did for one sent while the gateway was online. The offline replay carried the same `append` tag as the library's echo of an API send, which the upsert handler dropped wholesale; it now skips only the ids this session sent itself, and the phone's reactions, edits and revokes from that window are replayed the same way ([#1667](https://github.com/rmyndharis/OpenWA/issues/1667)).- Baileys sessions no longer drop the inbound messages WhatsApp queued while they were down. The offline replay is tagged `append`, which the upsert handler treated as history and skipped for anything older than the reconnect, so every message sent during an outage was never stored and never dispatched ([#1660](https://github.com/rmyndharis/OpenWA/issues/1660)). Thanks @fransarni for the report.-- A whatsapp-web.js session that comes up without its page-side call hook says so in the log instead of silently never reporting an incoming call. The hook is installed last in the same page evaluate as the message listeners, so the session stays healthy for messages either way ([#1655](https://github.com/rmyndharis/OpenWA/issues/1655)).+- A whatsapp-web.js session that comes up without its page-side call hook says so in the log instead of silently never reporting an incoming call. The hook is installed part-way through the same page evaluate as the message listeners, which run before it, so the session stays healthy for messages either way ([#1655](https://github.com/rmyndharis/OpenWA/issues/1655)).- Stopping, unlinking or force-killing a session announces `session.status: disconnected` after the engine is released, not while it is still tearing down, so a dashboard tab or a webhook consumer no longer learns the session is down in the one moment the API still reports its engine as loaded. On whatsapp-web.js that window lasted as long as Chromium took to close, and left an open QR modal on a dead code with the started actions still offered ([#1649](https://github.com/rmyndharis/OpenWA/issues/1649)).- The dashboard blanks a session's displayed QR code as soon as the session disconnects, so a code minted by a connection that is gone is never left on screen to be scanned ([#1649](https://github.com/rmyndharis/OpenWA/issues/1649)).- A pairing-code request whose retry budget runs out on a reloading WhatsApp Web page answers `503` instead of `500`, so a client can tell a retryable transport failure from a broken gateway ([#1654](https://github.com/rmyndharis/OpenWA/issues/1654)).@@ -95,7 +95,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- `adm-zip` moves to `0.6.1`, which bounds the memory a declared uncompressed size can ask for (GHSA-7q85-xj36-vmfc) and stops extraction following symlinks out of the target directory. The plugin installer reads entries one at a time under its own byte cap rather than extracting the archive, so neither vector was reachable there.- Baileys sessions with a SOCKS4 proxy fetch through it instead of connecting direct: inbound media, the WhatsApp Web version lookup, the initial-sync payloads and a product card's image URL, which 0.23.5 routed through HTTP, HTTPS and SOCKS5 proxies only ([#1626](https://github.com/rmyndharis/OpenWA/issues/1626)).-- A media URL passed to a send route or to `POST /api/sessions/{sessionId}/media/convert`, and the link preview of a text send, are fetched through the named session's egress proxy on both engines, instead of leaving from the gateway's own address ([#1626](https://github.com/rmyndharis/OpenWA/issues/1626)).+- A media URL passed to a send route or to `POST /api/sessions/{sessionId}/media/convert/voice` or `.../convert/video`, and the link preview of a text send, are fetched through the named session's egress proxy on both engines, instead of leaving from the gateway's own address ([#1626](https://github.com/rmyndharis/OpenWA/issues/1626)).## [0.23.5] - 2026-09-15diff --git a/docs/14-migration-guide.md b/docs/14-migration-guide.mdindex de85f5caf..5e39f07ec 100644--- a/docs/14-migration-guide.md+++ b/docs/14-migration-guide.md@@ -755,7 +755,7 @@ docker compose run --rm openwa-api npm run migration:run:prod| Release | Change | Action || -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| `0.23.6` | A media URL passed to a send route or to `POST /media/convert`, and the link preview of a text send, are fetched through the egress proxy of the session named in the request instead of leaving from the gateway's own address | Set `SESSION_PROXY_URL_FETCH=false` if a session proxy is a WhatsApp-only route that cannot reach arbitrary media hosts |+| `0.23.6` | A media URL passed to a send route or to `POST /media/convert/voice` or `.../convert/video`, and the link preview of a text send, are fetched through the egress proxy of the session named in the request instead of leaving from the gateway's own address | Set `SESSION_PROXY_URL_FETCH=false` if a session proxy is a WhatsApp-only route that cannot reach arbitrary media hosts || `0.23.0` | Typed SDK clients: `markRead` and `subscribePresence` each take their own request type instead of the shared `MarkChatRequest`, which now serves `markUnread` alone | Go and Java: swap the type at both call sites. Typed Python: only at `markRead`, its `subscribePresence` body being structurally identical. JavaScript and PHP need no change; the wire body is unchanged || `0.22.0` | Baileys refuses a reply whose quoted id, or a forward whose `fromChatId`, does not name the addressed chat, with the `404` whatsapp-web.js already answered; leaving a group, unsubscribing from a channel and labelling a channel surface WhatsApp's refusal; membership requests for an id that is not a group are refused | Handle a refusal on those six calls, which previously answered `200` whatever happened || `0.22.0` | Typed SDK clients narrow their request bodies: 19 Python request types mark the fields the server requires, and Go and Java type the proxy scheme, call kind, membership method, chat state, pin window and status font as enums | Pass the named constants instead of bare strings or numbers and supply every required field; untyped callers are unaffected |diff --git a/docs/29-engine-capability-matrix.md b/docs/29-engine-capability-matrix.mdindex ab0663462..6b77b9d33 100644--- a/docs/29-engine-capability-matrix.md+++ b/docs/29-engine-capability-matrix.md@@ -161,22 +161,23 @@ patches are a separate matter: π§ΒΉ underwrites every wwjs cell and π§β΅ evthat sense every row does depend on a patch on each side. "Patch-dependent" below means therow-level marks.-| Patch | Matrix rows that depend on it |-| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |-| π§ΒΉ message-id backport | **The whole wwjs column** (header-marked, not repeated per row): every wwjs cell that sends, receives or resolves a message id. On unpatched 1.34.7 against WhatsApp Web β₯ 2.3000.x, sends return no message object and chat/media reads throw the minified `r: r`. Not row-specific, so the wwjs column header carries `π§ΒΉ`. |-| π§Β² status-send repair | `postTextStatus`, `postImageStatus`, `postVideoStatus`, `postVoiceStatus` β **wwjs cells only**. Stock 1.34.7 throws before any status send on current WhatsApp Web builds. These four rows are β on both engines, but the wwjs side works only because of this patch. |-| π§Β³ newsletter link preview | `sendTextMessage` (and any send carrying a link preview) **to a channel JID** on wwjs. Row-marked on `sendTextMessage` as the common case. |-| π§β΄ ready-sync | `initialize` on wwjs (warm-restore readiness race). Row-marked. |-| π§β΅ app-state resync bound | No single row β keeps the Baileys socket's app-state resync from spinning (~1000 wasted 60s queries/day). Connection health under **every baileys cell**; the baileys column header carries `π§β΅`. |-| π§βΆ newsletter-create parse | `createChannel` on **baileys** β without it the call always answers 500 and leaks the channel it just created. Row-marked. |-| π§β· participant arity | `removeParticipants`, `promoteParticipants`, `demoteParticipants` on **wwjs**. Without it a request naming only non-members throws an arity assertion on removal, and promote/demote answer `200` for people WhatsApp never touched; the patch returns one boolean per REQUESTED id so the adapter reports a real per-participant outcome. Row-marked. |-| π§βΉ group description | `setGroupDescription` on **wwjs**. Without it every call throws in the page and answers a bare `500`, so the capability is dead rather than degraded; `setGroupSubject` beside it is unaffected. Row-marked. |-| π§βΈ block/unblock | `blockContact`, `unblockContact` on **wwjs**. Without it both answer an opaque `500` on every id, so the capability is dead rather than degraded; the blocklist read still works, which makes the failure look one-sided. |+| Patch | Matrix rows that depend on it |+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| π§ΒΉ message-id backport | **The whole wwjs column** (header-marked, not repeated per row): every wwjs cell that sends, receives or resolves a message id. On unpatched 1.34.7 against WhatsApp Web β₯ 2.3000.x, sends return no message object and chat/media reads throw the minified `r: r`. Not row-specific, so the wwjs column header carries `π§ΒΉ`. |+| π§Β² status-send repair | `postTextStatus`, `postImageStatus`, `postVideoStatus`, `postVoiceStatus` β **wwjs cells only**. Stock 1.34.7 throws before any status send on current WhatsApp Web builds. These four rows are β on both engines, but the wwjs side works only because of this patch. |+| π§Β³ newsletter link preview | `sendTextMessage` (and any send carrying a link preview) **to a channel JID** on wwjs. Row-marked on `sendTextMessage` as the common case. |+| π§β΄ ready-sync | `initialize` on wwjs (warm-restore readiness race). Row-marked. |+| π§β΅ app-state resync bound | No single row β keeps the Baileys socket's app-state resync from spinning (~1000 wasted 60s queries/day). Connection health under **every baileys cell**; the baileys column header carries `π§β΅`. |+| π§βΆ newsletter-create parse | `createChannel` on **baileys** β without it the call always answers 500 and leaks the channel it just created. Row-marked. |+| π§β· participant arity | `removeParticipants`, `promoteParticipants`, `demoteParticipants` on **wwjs**. Without it a request naming only non-members throws an arity assertion on removal, and promote/demote answer `200` for people WhatsApp never touched; the patch returns one boolean per REQUESTED id so the adapter reports a real per-participant outcome. Row-marked. |+| π§βΉ group description | `setGroupDescription` on **wwjs**. Without it every call throws in the page and answers a bare `500`, so the capability is dead rather than degraded; `setGroupSubject` beside it is unaffected. Row-marked. |+| π§βΈ block/unblock | `blockContact`, `unblockContact` on **wwjs**. Without it both answer an opaque `500` on every id, so the capability is dead rather than degraded; the blocklist read still works, which makes the failure look one-sided. |+| π§ΒΉβ° media send repair | Every **wwjs** send that carries media: `sendImageMessage`, `sendVideoMessage`, `sendAudioMessage`, `sendVoiceMessage`, `sendDocumentMessage`, `sendStickerMessage` and the media status posts. On the WhatsApp Web builds from 2026-09-17 the library's own id is clobbered by the media model and every such send answers a bare `500`, while text sends keep working. Not row-marked: it covers a whole class of rows rather than one. |Rows that are β on **both** engines where one side is patch-dependent: `initialize` (π§β΄ wwjs),`sendTextMessage` (π§Β³ wwjs), `postTextStatus` / `postImageStatus` / `postVideoStatus` /`postVoiceStatus` (π§Β² wwjs), `removeParticipants` / `promoteParticipants` / `demoteParticipants`-(π§β· wwjs), `setGroupDescription` (π§βΉ wwjs). Everything else that is β -both carries no row-level mark, but still+(π§β· wwjs), `setGroupDescription` (π§βΉ wwjs), and every media-carrying send (π§ΒΉβ° wwjs). Everything else that is β -both carries no row-level mark, but stillrests on the column-wide π§ΒΉ (wwjs) and π§β΅ (baileys) β no row runs on stock library code on bothsides.diff --git a/scripts/postinstall.js b/scripts/postinstall.jsindex 6a9d772e7..2d2c3b120 100644--- a/scripts/postinstall.js+++ b/scripts/postinstall.js@@ -1,7 +1,7 @@/*** Post-install hook (npm `postinstall`).*- * Ten conditional steps, each skipped when its target is absent so the hook is a no-op where the+ * Eleven conditional steps, each skipped when its target is absent so the hook is a no-op where the* piece is missing (the Docker builder stage copies package*.json long before any source):** 1. `npm ci` inside dashboard/ when dashboard/ exists β the dashboard carries its own lockfile anddiff --git a/src/engine/adapters/wwebjs-call-hook-check.ts b/src/engine/adapters/wwebjs-call-hook-check.tsindex 8d3cf3c42..2e4e21604 100644--- a/src/engine/adapters/wwebjs-call-hook-check.ts+++ b/src/engine/adapters/wwebjs-call-hook-check.ts@@ -33,10 +33,10 @@ function readCallHookState(): boolean | null {/*** Warn when a ready session's page carries no call hook.*- * whatsapp-web.js installs the call hook in the same `evaluate` as its message listeners, and that- * evaluate has no `try`/`catch`: a module that stops resolving earlier in it leaves the message- * bridge registered and the call hook silently absent. The session then looks completely healthy,- * keeps delivering messages, and never reports a single incoming call. Operators have no way to see+ * whatsapp-web.js installs the call hook part-way through the same `evaluate` as its message+ * listeners, and that evaluate has no `try`/`catch`: a module that stops resolving before it leaves+ * the message bridge registered and the call hook silently absent. The session then looks completely+ * healthy, keeps delivering messages, and never reports a single incoming call. Operators have no way to see* that from the outside, so say it in the log.** Deliberately advisory: it never changes the session's status. Detection is the only thing lost,diff --git a/src/engine/adapters/wwebjs-lifecycle.ts b/src/engine/adapters/wwebjs-lifecycle.tsindex 0c6aee180..0788cdfd8 100644--- a/src/engine/adapters/wwebjs-lifecycle.ts+++ b/src/engine/adapters/wwebjs-lifecycle.ts@@ -788,9 +788,10 @@ export class WwebjsLifecycle {// gets the companion unlinked (~5m later β disconnected: LOGOUT, #982). Dismiss it best-effort// and fall back to ACTION_REQUIRED. Started after READY so a non-ready session never arms it.this.host.startOnboardingWatcher();- // whatsapp-web.js installs its incoming-call hook as the LAST statement of the same page- // evaluate that registers the message listeners, and that evaluate has no try/catch: a module- // that stops resolving earlier in it leaves the message bridge live and the call hook absent.+ // whatsapp-web.js installs its incoming-call hook part-way through the same page evaluate that+ // registers the message listeners, and that evaluate has no try/catch: a module that stops+ // resolving before it leaves the message bridge live and the call hook absent (and takes the+ // chat listeners registered after it as well).// The session then looks healthy, keeps delivering messages, and reports no call at all. Warn// once per ready rather than leaving that silent; nothing else changes, since only detection is// lost. Fire-and-forget: a diagnostic must never delay or fail the promotion to READY.