Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs: say what the code does, and finish the punctuation pass
Yudhi Armyndharisb343687993ef
diff --git a/.env.example b/.env.exampleindex a4d706163..533824562 100644--- a/.env.example+++ b/.env.example@@ -260,7 +260,8 @@ OPENWA_PIDS_LIMIT=2048# Cap on the in-memory lid->phone mirror used for synchronous resolution on the dispatch hot path.# The table remains the source of truth; a cache miss falls back to engine re-resolution, so this# trades a re-resolution for bounded memory on a long-running, contact-heavy account. 0 disables the-# cap (legacy unbounded behaviour). Default 5000.+# cap (legacy unbounded behaviour) and, with it, the record of which lids the table has no row for,+# so an unmapped lid queries the table again on every dispatch. Default 5000.# LID_MAPPING_CACHE_MAX=5000# Per-map cap on the Baileys session store's in-memory maps (contacts, chats, lastMessages, lidToPn,diff --git a/CHANGELOG.md b/CHANGELOG.mdindex eacf162ef..f91306984 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -38,8 +38,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- A session proxy whose credentials contain a bare `%` is refused by `POST /api/sessions` and `PATCH /api/sessions/:sessionId/proxy` when it is set, instead of being stored and then failing every later start and every proxied URL fetch with an opaque `URI malformed`.- A WebSocket handshake whose transport closes while the key is being validated no longer burns a slot of the per-key connection cap for the life of the process.- A repeated query parameter on an ingress verification challenge is read as its first value instead of answering `500`: the value arrives from Express as an array and reached a constant-time compare that accepts only strings.-- A plugin's declared ingress ack can no longer write the response headers that decide how a browser treats its own reflected body, set a cookie on the gateway's origin, or claim a transfer or content encoding the ack does not actually use, which made the response undecodable and sent the provider back to retry a delivery already queued. The declared content type still applies, through the allowlist that already governed it.-- An ingress route whose manifest declares a non-string ack body or header value is refused at install and at boot, naming the field, instead of loading and then answering every delivery with that part of the ack silently missing.+- A plugin's declared ingress ack can no longer write the response headers that decide how a browser treats its own reflected body, set a cookie on the gateway's origin, or take over how the response is framed and decoded. A declared content encoding described bytes the ack does not carry, so the provider failed to decode it and retried a delivery already queued; a declared transfer encoding re-framed a body the host had already given a length; and a declared `Trailer` made Node refuse to write the response at all. The declared content type still applies, through the allowlist that already governed it.+- An ingress route whose manifest declares a non-string ack body or header value is refused at install and at boot, naming the field, instead of loading and then answering every delivery with that part of the ack silently missing. An already-installed plugin with such a manifest stops loading on upgrade and is recorded in error until the manifest is corrected, which is the same treatment every other manifest fault gets.- Uploading a zip whose trailer parses but whose directory does not answers `400`, not `500`.- A `socks5://` or `socks4://` proxy at an IPv6 literal connects: the brackets `URL` keeps were going on the wire as part of a hostname.- A Baileys session whose credentials carry no LID of their own no longer reports a `group.join` for a group it created itself: every LID comparison answered false, so the creator was never recognised. The session's own LID mapping settles it instead.@@ -48,7 +48,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- A QR code that arrives while the dashboard is asking the server about a disconnect no longer has its modal closed underneath it. The handler blanks the displayed code, re-reads the session list, and closed the modal when the answer said no engine was left; a reconnect completing inside that window had already pushed a fresh, scannable code.- Escape dismisses the Chats emoji picker instead of closing the whole conversation behind it.- A click on a WhatsApp Business prompt quotes the prompt in the stored reply, so the dashboard renders the question above the answer instead of an empty quote box.-- A send that quotes a message stores the quoted text, whatever the send is. Only replies did: an image, video, document, location, contact, poll or text sent with `quotedMessageId` stored the quoted id with an empty body, and the dashboard drew a blank quote box above it.+- A send that quotes a message stores the quoted text, whatever the send is. Only replies did: an image, video, document, location, contact, poll or text sent with `quotedMessageId` stored the quoted id with an empty body, and the dashboard drew a blank quote box above it. A quoted message that has no text of its own, a caption-less image for instance, still renders as an empty box; only its text is recovered here.- A template prompt that numbers only some of its buttons no longer answers the bot with an index belonging to a different button. A template that carries its own numbering is answered with it, one that carries none is answered by position, and a choice left unnumbered inside a numbered template is answered by id alone, with no index at all. Such a choice is still offered in `buttons[]` and still accepted by the click route.- A proxy password no longer reaches the log. A failed SOCKS connect carries the whole proxy config as the error's only property, and `BAILEYS_LOG_LEVEL=debug` wrote it to stdout verbatim.- Baileys sessions list the saved address book again after a process restart. WhatsApp sends neither history nor an app-state snapshot to a device that has synced once, and the contact store is in memory, so a restarted gateway answered `GET /api/sessions/:sessionId/contacts` with only the peers it had seen since. Each session now re-pulls the snapshot of the app-state collection that carries saved contacts, once per engine start. That also repairs a PARTIAL address book, which is the usual shape: during the initial sync the library's event buffer folds the saved-contact updates into the history batch it is already holding, where their names are stripped as chat titles, so the store keeps plenty of contacts with the saved ones missing. The list is also the address book only: a peer known by pushname alone is no longer listed, while `GET .../contacts/:contactId` still resolves it with `isMyContact: false`, and a chat title from history sync no longer overwrites a saved name. Thanks @gabrielmmoraes1999.@@ -56,7 +56,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 library installs the hook only when the page exposes the call collection it expects, so a WhatsApp Web build that moves that collection leaves calls undetected while messages keep working. The check is skipped on an install whose whatsapp-web.js patches were not applied, where a session can reach ready before the hook is installed and the warning would be false ([#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 library installs the hook only when the page's call-collection module exposes an `on` method, so a WhatsApp Web build that keeps the module but drops that method leaves calls undetected while messages keep working. The check stays quiet when it cannot tell, and is skipped entirely when the `patch-wwebjs-ready-sync` install-time patch is missing, since a session can then reach ready before the hook is installed and the warning would be false ([#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)).diff --git a/dashboard/src/i18n/locales/ar.json b/dashboard/src/i18n/locales/ar.jsonindex 32438d74e..227f5a848 100644--- a/dashboard/src/i18n/locales/ar.json+++ b/dashboard/src/i18n/locales/ar.json@@ -318,7 +318,7 @@"created": "تاريخ الإنشاء","lastActive": "آخر نشاط","autoRejectCalls": "الرفض التلقائي للمكالمات",- "autoRejectCallsHint": "يتم رفض المكالمات الواردة فور رنينها. ولا يزال الويب هوك call.received يُرسل قبل ذلك. يسري على المكالمة التالية — دون الحاجة إلى إعادة التشغيل. مع محرك Baileys فقط: لا يستطيع whatsapp-web.js رفض المكالمات."+ "autoRejectCallsHint": "يتم رفض المكالمات الواردة فور رنينها. ولا يزال الويب هوك call.received يُرسل قبل ذلك. يسري على المكالمة التالية, دون الحاجة إلى إعادة التشغيل. مع محرك Baileys فقط: لا يستطيع whatsapp-web.js رفض المكالمات."},"proxy": {"title": "Proxy Configuration",diff --git a/dashboard/src/i18n/locales/de.json b/dashboard/src/i18n/locales/de.jsonindex e9c6d2591..b6f13b729 100644--- a/dashboard/src/i18n/locales/de.json+++ b/dashboard/src/i18n/locales/de.json@@ -307,7 +307,7 @@"created": "Erstellt","lastActive": "Zuletzt aktiv","autoRejectCalls": "Anrufe automatisch ablehnen",- "autoRejectCallsHint": "Eingehende Anrufe werden abgelehnt, sobald sie klingeln. Der Webhook call.received wird trotzdem zuerst ausgelöst. Gilt ab dem nächsten Anruf — kein Neustart nötig. Nur mit der Baileys-Engine: whatsapp-web.js kann keine Anrufe ablehnen."+ "autoRejectCallsHint": "Eingehende Anrufe werden abgelehnt, sobald sie klingeln. Der Webhook call.received wird trotzdem zuerst ausgelöst. Gilt ab dem nächsten Anruf, kein Neustart nötig. Nur mit der Baileys-Engine: whatsapp-web.js kann keine Anrufe ablehnen."},"proxy": {"title": "Proxy Configuration",diff --git a/dashboard/src/i18n/locales/en.json b/dashboard/src/i18n/locales/en.jsonindex 12bab2df8..e9b160269 100644--- a/dashboard/src/i18n/locales/en.json+++ b/dashboard/src/i18n/locales/en.json@@ -312,7 +312,7 @@"created": "Created","lastActive": "Last Active","autoRejectCalls": "Auto-reject calls",- "autoRejectCallsHint": "Incoming calls are declined as soon as they ring. The call.received webhook still fires first. Applies to the next call — no restart needed. Baileys engine only: whatsapp-web.js cannot reject calls."+ "autoRejectCallsHint": "Incoming calls are declined as soon as they ring. The call.received webhook still fires first. Applies to the next call, no restart needed. Baileys engine only: whatsapp-web.js cannot reject calls."},"proxy": {"title": "Proxy Configuration",diff --git a/dashboard/src/i18n/locales/fr.json b/dashboard/src/i18n/locales/fr.jsonindex 0c57be4d8..c962d183d 100644--- a/dashboard/src/i18n/locales/fr.json+++ b/dashboard/src/i18n/locales/fr.json@@ -307,7 +307,7 @@"created": "Créé le","lastActive": "Dernière activité","autoRejectCalls": "Rejeter automatiquement les appels",- "autoRejectCallsHint": "Les appels entrants sont refusés dès qu'ils sonnent. Le webhook call.received est tout de même émis avant. S'applique au prochain appel — aucun redémarrage nécessaire. Moteur Baileys uniquement : whatsapp-web.js ne peut pas refuser les appels."+ "autoRejectCallsHint": "Les appels entrants sont refusés dès qu'ils sonnent. Le webhook call.received est tout de même émis avant. S'applique au prochain appel, aucun redémarrage nécessaire. Moteur Baileys uniquement : whatsapp-web.js ne peut pas refuser les appels."},"proxy": {"title": "Proxy Configuration",diff --git a/dashboard/src/i18n/locales/he.json b/dashboard/src/i18n/locales/he.jsonindex b660b7c0f..5ecc9093f 100644--- a/dashboard/src/i18n/locales/he.json+++ b/dashboard/src/i18n/locales/he.json@@ -314,7 +314,7 @@"created": "נוצר בתאריך","lastActive": "פעילות אחרונה","autoRejectCalls": "דחיית שיחות אוטומטית",- "autoRejectCallsHint": "שיחות נכנסות נדחות ברגע שהן מצלצלות. ה-webhook call.received עדיין נשלח לפני כן. חל מהשיחה הבאה — ללא צורך בהפעלה מחדש. במנוע Baileys בלבד: whatsapp-web.js לא יכול לדחות שיחות."+ "autoRejectCallsHint": "שיחות נכנסות נדחות ברגע שהן מצלצלות. ה-webhook call.received עדיין נשלח לפני כן. חל מהשיחה הבאה, ללא צורך בהפעלה מחדש. במנוע Baileys בלבד: whatsapp-web.js לא יכול לדחות שיחות."},"proxy": {"title": "Proxy Configuration",diff --git a/dashboard/src/i18n/locales/it.json b/dashboard/src/i18n/locales/it.jsonindex aeee22dc3..43047e1a6 100644--- a/dashboard/src/i18n/locales/it.json+++ b/dashboard/src/i18n/locales/it.json@@ -307,7 +307,7 @@"created": "Creata","lastActive": "Ultima Attività","autoRejectCalls": "Rifiuta automaticamente le chiamate",- "autoRejectCallsHint": "Le chiamate in arrivo vengono rifiutate appena squillano. Il webhook call.received viene comunque inviato prima. Si applica alla prossima chiamata — nessun riavvio necessario. Solo con il motore Baileys: whatsapp-web.js non può rifiutare le chiamate."+ "autoRejectCallsHint": "Le chiamate in arrivo vengono rifiutate appena squillano. Il webhook call.received viene comunque inviato prima. Si applica alla prossima chiamata, nessun riavvio necessario. Solo con il motore Baileys: whatsapp-web.js non può rifiutare le chiamate."},"proxy": {"title": "Configurazione proxy",diff --git a/dashboard/src/i18n/locales/pt-BR.json b/dashboard/src/i18n/locales/pt-BR.jsonindex ad372cf07..0be002035 100644--- a/dashboard/src/i18n/locales/pt-BR.json+++ b/dashboard/src/i18n/locales/pt-BR.json@@ -307,7 +307,7 @@"created": "Criado em","lastActive": "Última atividade","autoRejectCalls": "Rejeitar chamadas automaticamente",- "autoRejectCallsHint": "As chamadas recebidas são recusadas assim que tocam. O webhook call.received continua sendo enviado antes. Vale a partir da próxima chamada — sem reiniciar. Somente no mecanismo Baileys: o whatsapp-web.js não consegue recusar chamadas."+ "autoRejectCallsHint": "As chamadas recebidas são recusadas assim que tocam. O webhook call.received continua sendo enviado antes. Vale a partir da próxima chamada, sem reiniciar. Somente no mecanismo Baileys: o whatsapp-web.js não consegue recusar chamadas."},"proxy": {"title": "Proxy Configuration",diff --git a/dashboard/src/i18n/locales/te.json b/dashboard/src/i18n/locales/te.jsonindex b700773de..e9b488c97 100644--- a/dashboard/src/i18n/locales/te.json+++ b/dashboard/src/i18n/locales/te.json@@ -307,7 +307,7 @@"created": "సృష్టించబడింది","lastActive": "చివరిసారి యాక్టివ్","autoRejectCalls": "కాల్లను ఆటోమేటిక్గా తిరస్కరించు",- "autoRejectCallsHint": "ఇన్కమింగ్ కాల్లు మోగిన వెంటనే తిరస్కరించబడతాయి. call.received వెబ్హుక్ మాత్రం ముందుగా పంపబడుతుంది. తదుపరి కాల్ నుండి వర్తిస్తుంది — పునఃప్రారంభం అవసరం లేదు. Baileys ఇంజిన్లో మాత్రమే: whatsapp-web.js తో కాల్లను తిరస్కరించడం సాధ్యం కాదు."+ "autoRejectCallsHint": "ఇన్కమింగ్ కాల్లు మోగిన వెంటనే తిరస్కరించబడతాయి. call.received వెబ్హుక్ మాత్రం ముందుగా పంపబడుతుంది. తదుపరి కాల్ నుండి వర్తిస్తుంది, పునఃప్రారంభం అవసరం లేదు. Baileys ఇంజిన్లో మాత్రమే: whatsapp-web.js తో కాల్లను తిరస్కరించడం సాధ్యం కాదు."},"proxy": {"title": "Proxy Configuration",diff --git a/dashboard/src/i18n/locales/tr.json b/dashboard/src/i18n/locales/tr.jsonindex 5c61e2666..b4360b8bd 100644--- a/dashboard/src/i18n/locales/tr.json+++ b/dashboard/src/i18n/locales/tr.json@@ -312,7 +312,7 @@"created": "Oluşturuldu","lastActive": "Son Görülme","autoRejectCalls": "Aramaları otomatik reddet",- "autoRejectCallsHint": "Gelen aramalar çaldığı anda reddedilir. call.received webhook'u yine de ilk olarak tetiklenir. Bir sonraki arama için geçerlidir — yeniden başlatma gerekmez. Yalnızca Baileys motorunda: whatsapp-web.js aramaları reddedemez."+ "autoRejectCallsHint": "Gelen aramalar çaldığı anda reddedilir. call.received webhook'u yine de ilk olarak tetiklenir. Bir sonraki arama için geçerlidir, yeniden başlatma gerekmez. Yalnızca Baileys motorunda: whatsapp-web.js aramaları reddedemez."},"proxy": {"title": "Proxy Configuration",diff --git a/dashboard/src/i18n/locales/zh-CN.json b/dashboard/src/i18n/locales/zh-CN.jsonindex 3ee83140f..76270d56a 100644--- a/dashboard/src/i18n/locales/zh-CN.json+++ b/dashboard/src/i18n/locales/zh-CN.json@@ -382,7 +382,7 @@"phonePlaceholder": "例如:919876543210","phoneHint": "仅填数字(不含 +、空格或连字符),使用国际格式(国家/地区代码 + 号码)。","relinkWarning": "在 whatsapp-web.js 引擎上,为已经有关联会话的号码请求配对码,可能会导致 WhatsApp 解除该设备的关联。如果该会话必须保持运行,请改用二维码标签页。",- "invalidPhone": "请输入有效的电话号码:6–15 位数字,国家/地区代码在前,不含任何符号。",+ "invalidPhone": "请输入有效的电话号码:6-15 位数字,国家/地区代码在前,不含任何符号。","generateButton": "生成配对码","generating": "正在生成配对码...","codeLabel": "您的配对码",diff --git a/docs/05-database-design.md b/docs/05-database-design.mdindex 05d07a8d3..f02ef339c 100644--- a/docs/05-database-design.md+++ b/docs/05-database-design.md@@ -377,8 +377,8 @@ clears it, and so does a gateway restart.| Key | Default | Effect || ---------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |-| `maxReconnectAttempts` | unlimited | Reconnect attempt cap, clamped to 0–20 (`0` disables reconnect entirely). Bounds the gateway's own reconnect: every reconnect on whatsapp-web.js, and on Baileys only the one after a logged-out close |-| `reconnectBaseDelay` | `5000` ms | Base delay of the reconnect backoff, clamped to 1000–300000 ms. Same engine scope as `maxReconnectAttempts` |+| `maxReconnectAttempts` | unlimited | Reconnect attempt cap, clamped to 0-20 (`0` disables reconnect entirely). Bounds the gateway's own reconnect: every reconnect on whatsapp-web.js, and on Baileys only the one after a logged-out close |+| `reconnectBaseDelay` | `5000` ms | Base delay of the reconnect backoff, clamped to 1000-300000 ms. Same engine scope as `maxReconnectAttempts` || `autoRejectCalls` | `false` | Auto-reject an incoming call as soon as it rings (Baileys only) |Set them at creation with `POST /api/sessions`, or on an existing session withdiff --git a/docs/25-integration-fabric.md b/docs/25-integration-fabric.mdindex c360fd95d..d30b252f0 100644--- a/docs/25-integration-fabric.md+++ b/docs/25-integration-fabric.md@@ -269,11 +269,14 @@ Within major 1 the surface grows additively. A route's optional `response` contr`headers`, rendered host-side with `{rawBody}`/`{timestamp}`/`{id}` templates from the verified request),and an advisory `deadlineMs` — lets an adapter shape the synchronous HTTP response the provider sees; theplugin still always runs async, and a route with no `response` is byte-identical to today's default-fast-ack. `ack.body` and every `ack.headers` value must be strings, and a manifest that declares-otherwise is refused at install and at boot. A declared header is dropped rather than written when it-names the content type (decided by the allowlist in §25.8), a framing or encoding header (`content-length`,-`transfer-encoding`, `content-encoding`, since the response is framed by the host and never compressed), a-cookie, a CORS header, or one of the browser-facing protections the host sets for every response.+fast-ack. `ack.body` and every `ack.headers` value must be strings, and a manifest that declares otherwise+is refused at install and at boot, which leaves that plugin in error until the manifest is fixed. A+declared header is dropped rather than written when it is one of these thirteen names: `content-type`+(decided by the allowlist in §25.8); `content-length`, `transfer-encoding`, `content-encoding` and+`trailer`, since the host frames the response itself and never compresses it; `set-cookie`,+`access-control-allow-origin` and `access-control-allow-credentials`; and `content-security-policy`,+`x-content-type-options`, `x-frame-options`, `strict-transport-security` and `referrer-policy`, the+response protections the host sets for every request. Every other declared header goes out verbatim.The `mode: 'sync-reply'` value is **deprecated** in favor of `response`: it was inert dead codethat was never wired to the HTTP response (the pipeline is always async + fast-ack), and it is kept in thediff --git a/docs/29-engine-capability-matrix.md b/docs/29-engine-capability-matrix.mdindex 0f573c731..7ba568ced 100644--- a/docs/29-engine-capability-matrix.md+++ b/docs/29-engine-capability-matrix.md@@ -25,7 +25,7 @@ Statuses used in the tables:Two complementary views:-- **29.4 — the OpenWA contract view.** Rows are the 113 `IWhatsAppEngine` methods; use it to see+- **29.4, the OpenWA contract view.** Rows are the 113 `IWhatsAppEngine` methods; use it to seewhat a REST caller gets per engine. Source of truth: `src/engine/engine-capability-matrix.ts`(per-cell `evidence` strings cite the exact library `file:symbol` inspected).- **29.5 — the full engine inventory.** Rows are **every method the installed libraries expose**,@@ -179,10 +179,11 @@ Rows that are ✅ on **both** engines where one side is patch-dependent: `initia`sendTextMessage` (🔧³ wwjs), `postTextStatus` / `postImageStatus` / `postVideoStatus` /`postVoiceStatus` (🔧² wwjs), `removeParticipants` / `promoteParticipants` / `demoteParticipants`(🔧⁷ wwjs), `setGroupDescription` (🔧⁹ wwjs), `blockContact` / `unblockContact` (🔧⁸ wwjs), and-every media-carrying send (🔧¹⁰ wwjs). The last two are not marked in the rows themselves, because-each covers a whole class of rows rather than one; every other entry here is. Everything else that-is ✅-both carries no patch dependency of its own, but still rests on the column-wide 🔧¹ (wwjs) and-🔧⁵ (baileys), so no row runs on stock library code on both sides.+every media-carrying send (🔧¹⁰ wwjs). The last two carry no mark in the rows themselves and are+recorded in the table above instead: 🔧¹⁰ because it covers a whole class of rows rather than one,+🔧⁸ simply because its two rows were never marked. Everything else that is ✅-both carries no patch+dependency of its own, but still rests on the column-wide 🔧¹ (wwjs) and 🔧⁵ (baileys), so no row+runs on stock library code on both sides.### 29.3.3 Why no patch surfaces `transferChannelOwnership`'s swallowed reason@@ -208,7 +209,7 @@ opens `if (!channel) return false;` before its try, so its `false` conflates _ch_WhatsApp refused_, and the adapter answers 403 for both. That distinction is ours to make in our ownadapter and involves no library change.-## 29.4 Full capability matrix — the OpenWA contract view (113 methods)+## 29.4 Full capability matrix: the OpenWA contract view (113 methods)Legend recap: **✅** supported · **✅🔧ⁿ** supported via OpenWA patch `🔧ⁿ` (29.3) ·**❌ gap** adapter-gap · **❌ lib** library-limitation. Column headers carry the engine-wide@@ -888,7 +889,7 @@ adapter boundary — none silently stubs.✅ means works end-to-end — but these rows carry behavioral differences worth knowing:-- **`clickButton` (Baileys) — native-flow is unverified.** Classic `buttonsMessage` /+- **`clickButton` (Baileys), native-flow is unverified.** Classic `buttonsMessage` /`templateMessage` / `listMessage` prompts go through Baileys' `buttonReply` / `listReply`helpers. A native-flow `interactiveMessage` prompt is answered with the same template`buttonReply` shape; Baileys also has `InteractiveResponseMessage.nativeFlowResponseMessage`,@@ -907,7 +908,7 @@ adapter boundary — none silently stubs.`NotImplementedException` → HTTP 501) at `ensureNotChannelRecipient`(`wwebjs-messaging.ts:425` for the media funnel, `:492` for stickers). whatsapp-web.js calls`msg.avParams()`, removed in a recent WA Web build (upstream wwebjs#201823, unresolved).- Text→channel is unaffected, and Baileys has no such restriction — so these five rows answer `501`+ Text→channel is unaffected, and Baileys has no such restriction, so these five rows answer `501`without a per-row ❌ in 29.4.- **`sendStickerMessage` — what each engine converts.** Both engines guarantee the payload really isWebP, but they reach it differently and they do not accept the same inputs. whatsapp-web.js passesdiff --git a/sdk/go/calls.go b/sdk/go/calls.goindex 5fe9f8320..79bb8ac4d 100644--- a/sdk/go/calls.go+++ b/sdk/go/calls.go@@ -32,7 +32,7 @@ func (s *CallsService) base(sessionID string) string {// RejectCall rejects a ringing incoming call; callID comes from the// call.received event (CallReceivedPayload.CallID). A call can only be-// rejected while it is still ringing — otherwise the server responds 404.+// rejected while it is still ringing; otherwise the server responds 404.// Baileys only; whatsapp-web.js answers 501. Requires an OPERATOR-level key.func (s *CallsService) RejectCall(ctx context.Context, sessionID, callID string) (*SuccessResult, error) {var out SuccessResultdiff --git a/src/engine/adapters/baileys-lifecycle.ts b/src/engine/adapters/baileys-lifecycle.tsindex 715c388c1..7edc26e94 100644--- a/src/engine/adapters/baileys-lifecycle.ts+++ b/src/engine/adapters/baileys-lifecycle.ts@@ -433,7 +433,7 @@ export class BaileysLifecycle {sock.ev.on('groups.upsert', groups => this.host.handleGroupsUpsert(groups));sock.ev.on('group.join-request', event => this.host.handleGroupJoinRequest(event));sock.ev.on('messaging-history.set', history => {- // History sync copies conversation.displayName into `name`, which is a chat title — not the+ // History sync copies conversation.displayName into `name`, which is a chat title, not the// address-book saved name (that arrives via contacts.upsert from app-state contactAction).// Fold the title into notify so chat-name fallback still works, and leave `name` unset so// GET /contacts stays the agenda rather than every 1:1 the account has ever opened.diff --git a/src/engine/adapters/baileys-messaging.ts b/src/engine/adapters/baileys-messaging.tsindex 2a9edbe93..afe8b9685 100644--- a/src/engine/adapters/baileys-messaging.ts+++ b/src/engine/adapters/baileys-messaging.ts@@ -688,8 +688,8 @@ export class BaileysMessaging {// wwjs fires `message_create` for its own API sends, which SessionService turns into `message.sent`.// Baileys' own socket-sends echo back only as a `type:'append'` upsert, which handleMessagesUpsert// skips by the id send() recorded, so that event never fired for API sends. Emit the outbound- // "created" callback here for parity —- // best-effort and off the response path. No media re-download: the API caller already holds the+ // "created" callback here for parity: best-effort,+ // and off the response path. No media re-download: the API caller already holds the// payload and the REST send path persists it (wwjs, by contrast, does download it on its echo).void this.emitOwnSendEcho(sent);}diff --git a/src/engine/adapters/baileys-status.ts b/src/engine/adapters/baileys-status.tsindex 75b44e21f..59c7b8b19 100644--- a/src/engine/adapters/baileys-status.ts+++ b/src/engine/adapters/baileys-status.ts@@ -88,7 +88,7 @@ export class BaileysStatus {/*** Post a status (story) to `status@broadcast` with a denormalized `statusJidList` (the allow-list of* neutral recipients folded back to the engine dialect). Image/video variants route through here too.- * The outbound status echo is NOT persisted — status isn't a chat message (its id is recorded below+ * The outbound status echo is NOT persisted: status isn't a chat message (its id is recorded below* so handleMessagesUpsert skips the `type:'append'` echo as ours).*/private async postStatus(content: AnyMessageContent, options: StatusPostOptions): Promise<StatusResult> {diff --git a/src/engine/adapters/baileys.adapter.ts b/src/engine/adapters/baileys.adapter.tsindex 02940be15..5aa6bf2b4 100644--- a/src/engine/adapters/baileys.adapter.ts+++ b/src/engine/adapters/baileys.adapter.ts@@ -94,7 +94,7 @@ export class BaileysAdapter implements IWhatsAppEngine {private set sock(value: WASocket | null) {this.lifecycle.sock = value;}- /** Live-call cache handle — the map is owned by the events delegate (call events + rejectCall);+ /** Live-call cache handle: the map is owned by the events delegate (call events + rejectCall);* lifecycle teardown clears it so a late rejectCall() reports not-found on a dead socket. The* adapter keeps this alias for the unmodified spec, which reads `adapter.liveCalls` via a cast. */private get liveCalls(): Map<string, { callFrom: string; expiresAt: number }> {diff --git a/src/engine/adapters/whatsapp-web-js.adapter.spec.ts b/src/engine/adapters/whatsapp-web-js.adapter.spec.tsindex 93890841c..d0576b5f1 100644--- a/src/engine/adapters/whatsapp-web-js.adapter.spec.ts+++ b/src/engine/adapters/whatsapp-web-js.adapter.spec.ts@@ -2352,8 +2352,9 @@ describe('WhatsAppWebJsAdapter ready reconciliation (#251/#273)', () => {});// #1655: a session can be perfectly healthy for messages and unable to see a single incoming call,- // because whatsapp-web.js installs the call hook last in the same page evaluate as the message- // listeners. The page read that settles it is one line, so ready says it instead of staying quiet.+ // because whatsapp-web.js patches the call collection only when the page's module for it exposes+ // an `.on` method, and the rest of its evaluate completes either way. The page read that settles+ // it is one line, so ready says it instead of staying quiet.it('warns at ready when the page carries no call hook', async () => {const adapter = newAdapter();const logger = (adapter as unknown as { logger: { warn: jest.Mock } }).logger;@@ -3813,7 +3814,7 @@ describe('WhatsAppWebJsAdapter call event + rejectCall', () => {});it.each([{ id: '' }, { id: undefined }, { from: '' }, { from: undefined }, null])(- 'drops a malformed call (%o) — nothing emitted, nothing cached',+ 'drops a malformed call (%o): nothing emitted, nothing cached',malformed => {const { onCall, client } = wireCallHandler();diff --git a/src/engine/adapters/wwebjs-call-hook-check.spec.ts b/src/engine/adapters/wwebjs-call-hook-check.spec.tsindex 6d1ecbd83..371a508eb 100644--- a/src/engine/adapters/wwebjs-call-hook-check.spec.ts+++ b/src/engine/adapters/wwebjs-call-hook-check.spec.ts@@ -2,10 +2,10 @@ import { reportMissingCallHook } from './wwebjs-call-hook-check';/*** whatsapp-web.js detects an incoming call by patching ONE page function: the call collection's- * internal `Map.set`. It installs that patch only when the page exposes a call collection shaped the- * way it expects, so a WhatsApp Web build that moves or renames that collection leaves messages- * working and calls undetectable, with nothing in the log to say so. This check turns that silence- * into a warning.+ * internal `Map.set`. It installs that patch only when the page's module for the collection exposes+ * an `.on` function, so a build that keeps the module but drops that method leaves messages working+ * and calls undetectable, with nothing in the log to say so. This check turns that silence into a+ * warning, and stays quiet for the neighbouring shapes it cannot tell apart from a healthy page.*/describe('reportMissingCallHook', () => {const makeLogger = (): { warn: jest.Mock; debug: jest.Mock } => ({ warn: jest.fn(), debug: jest.fn() });diff --git a/src/engine/adapters/wwebjs-call-hook-check.ts b/src/engine/adapters/wwebjs-call-hook-check.tsindex 29d1c7f4f..c15874647 100644--- a/src/engine/adapters/wwebjs-call-hook-check.ts+++ b/src/engine/adapters/wwebjs-call-hook-check.ts@@ -33,13 +33,19 @@ function readCallHookState(): boolean | null {/*** Warn when a ready session's page carries no call hook.*- * whatsapp-web.js installs the call hook inside a conditional, part-way through the `evaluate` that- * registers its listeners: it patches the page's call collection only when the page exposes one- * shaped the way it expects. A WhatsApp Web build that moves or renames that collection skips the- * hook while the rest of the evaluate completes, so the session 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. (A stall inside the evaluate is not this case: the inbound- * message bridge is registered after the call hook, so it would stop message delivery too.)+ * whatsapp-web.js patches the call collection only when the page's module for it exposes an `.on`+ * function. That is the one failure this check can actually see: a WhatsApp Web build that keeps+ * the module and its internal Map but drops or renames `.on` makes the library skip the hook while+ * the rest of the evaluate completes, so the session 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.+ *+ * The neighbouring failures are NOT this one and are deliberately not reported. A build that+ * removes or renames the module makes the library's own `require` for it throw, which aborts the+ * whole evaluate and takes the inbound message bridge registered after it, so that session is+ * loudly broken for messages too. A build that restructures the collection past recognition leaves+ * {@link readCallHookState} with nothing to compare and it answers `null`. Both read as+ * inconclusive here, and inconclusive stays silent.** Deliberately advisory: it never changes the session's status. Detection is the only thing lost,* and a false alarm on an inconclusive read would send operators after a problem they do not have.@@ -59,7 +65,9 @@ export async function reportMissingCallHook(if (installed !== false) return;logger.warn('Incoming calls cannot be detected on this session: the page-side call hook is not installed. ' +- 'Messages are unaffected; restart the session to reinject it.',+ 'Messages are unaffected. This is a mismatch between whatsapp-web.js and the WhatsApp Web ' ++ 'build it loaded, so a restart only helps if the page was in a transient state; if it repeats, ' ++ 'the library needs an update. Switch the session to the Baileys engine to keep call events.',{ sessionId, action: 'call_hook_missing' },);}diff --git a/src/engine/adapters/wwebjs-lifecycle.ts b/src/engine/adapters/wwebjs-lifecycle.tsindex 1696328e5..7261aaf1e 100644--- a/src/engine/adapters/wwebjs-lifecycle.ts+++ b/src/engine/adapters/wwebjs-lifecycle.ts@@ -788,15 +788,14 @@ 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 inside a conditional, part-way through the- // page evaluate that registers its listeners: it patches the call collection only when the page- // exposes one shaped the way it expects. A WhatsApp Web build that moves or renames that- // collection skips the hook while the rest of the evaluate completes, so the session looks- // healthy, keeps delivering messages, and reports no call at all. (A stall inside that evaluate- // is a different, noisier shape: the inbound message bridge is registered AFTER the call hook,- // so it would take message delivery with it.) Warn once per ready rather than leaving the quiet- // case silent; nothing else changes, since only detection is lost. Fire-and-forget: a- // diagnostic must never delay or fail the promotion to READY.+ // whatsapp-web.js patches the call collection only when the page's module for it exposes an+ // `.on` function. A WhatsApp Web build that keeps the module but drops that method skips the+ // hook while the rest of the evaluate completes, so the session looks healthy, keeps delivering+ // messages, and reports no call at all. That quiet case is the one worth a line in the log; a+ // build that removes the module instead makes the library's own require throw, aborting the+ // evaluate and taking the inbound message bridge with it, which is loud on its own. Warn once+ // per ready; nothing else changes, since only detection is lost. Fire-and-forget: a diagnostic+ // must never delay or fail the promotion to READY.//// Skipped on a tree missing the ready-sync patch: without it the session can reach READY while// that same evaluate is still running, so the probe would read a page whose hook simply has not@@ -1086,8 +1085,11 @@ export class WwebjsLifecycle {// evaluate, so the next attempt stops the previous flow itself. Its `cancelPairingCode`// would on top of that return the page to QR mode, which is the opposite of what a retry// wants, and it is an unbounded page evaluate against the page that is already unwell, so- // awaiting it would add a full Puppeteer protocol timeout to each gap. What the abandoned- // flow does reach is the library's own CODE_RECEIVED event, which nothing here listens to.+ // awaiting it would add a full Puppeteer protocol timeout to each gap. The abandoned flow+ // is not inert: each tick of its interval asks WhatsApp for a fresh code and notifies the+ // phone, and its CODE_RECEIVED event reaches nothing here. What bounds it is the page, not+ // us: the interval dies with the next WhatsApp Web reload, which happens every few seconds+ // while the session is UNPAIRED, and with the session itself.await new Promise<void>(resolve => {const t = setTimeout(resolve, PAIRING_CODE_RETRY_DELAY_MS);t.unref?.();diff --git a/src/engine/engine-capability-matrix.ts b/src/engine/engine-capability-matrix.tsindex 5e102db4c..28f54b928 100644--- a/src/engine/engine-capability-matrix.ts+++ b/src/engine/engine-capability-matrix.ts@@ -314,8 +314,11 @@ export const CURATED_CAPABILITY_EXCEPTIONS: Record<string, MethodCapability> = {'checking no precondition; measured twice (2026-09-17, 2026-09-18) a request for a number that ' +'already had a linked session was followed within about a minute by WhatsApp revoking that ' +'device, whatsapp-web.js deleting its credentials and the session returning to qr_ready. It ' +- 'also arms an in-page 3-minute re-request interval that OpenWA cannot cancel (cancelPairingCode ' +- 'is not exposed) and notifies the phone on every code. baileys requestPairingCode ' ++ 'also arms an in-page 3-minute re-request interval that mints a fresh code and notifies the ' ++ 'phone on every tick. The interval lives in the page, so it dies with the next WhatsApp Web ' ++ 'reload (roughly every 20s while UNPAIRED) and with the session; the library does expose ' ++ 'cancelPairingCode, but it returns the page to QR mode, which is not what a retry wants. ' ++ 'baileys requestPairingCode ' +'(Socket/socket.js:596-650) writes only its own creds and sends one link_code_companion_reg IQ, ' +'with no shared page; no side effect was observed there.',},diff --git a/src/modules/integration/ingress-reconciler.service.ts b/src/modules/integration/ingress-reconciler.service.tsindex 2890e97dc..175cd6d27 100644--- a/src/modules/integration/ingress-reconciler.service.ts+++ b/src/modules/integration/ingress-reconciler.service.ts@@ -46,7 +46,7 @@ export interface IngressReconcileStats {* Closes the last silent-loss window of the fast-ack ingress pipeline. persist-before-ack makes the* ingress_events row durable, but durability alone is not delivery: a crash between the persist and* the enqueue, or a fire-and-forget enqueue whose outcome never gets recorded, strands the row- * 'pending' forever — a provider retry only hits the dedup oracle and is answered with the route's ack.+ * 'pending' forever: a provider retry only hits the dedup oracle and is answered with the route's ack.** The reconciler sweeps small batches of stale 'pending' rows and re-dispatches them through the* exact same IngressEnqueueService the live path uses (same deliveryId as BullMQ jobId, so a replaydiff --git a/src/modules/message/message-send.service.ts b/src/modules/message/message-send.service.tsindex 9e1a46c17..a4a664c89 100644--- a/src/modules/message/message-send.service.ts+++ b/src/modules/message/message-send.service.ts@@ -43,11 +43,12 @@ export interface SaveOutgoingMessageData {status?: MessageStatus;metadata?: Record<string, unknown>;/**- * Quoted id for a send that is a reply. Folded into `metadata.quotedMessage` here rather than- * by each sender so the nine send paths and `reply()` persist one shape — a row that quoted a- * message but records nothing is simply wrong history, and the dashboard reads this key to- * render the reply preview. The body is left empty: unlike `reply()`, the send paths do not- * look the quoted message up, and '' is already reply()'s own value when that lookup fails.+ * Quoted id for a send that quotes something. Folded into `metadata.quotedMessage` at the shared+ * persist rather than by each sender, so the nine send paths and `reply()` record one shape: a row+ * that quoted a message but records nothing is simply wrong history, and the dashboard reads this+ * key to render the quote preview. The quoted body is looked up there too, so a sender does not+ * have to remember; a quoted row with no text of its own (a caption-less image, say) still yields+ * '', which the preview renders as an empty box.*/quotedMessageId?: string;}diff --git a/src/modules/session/dto/create-session.dto.ts b/src/modules/session/dto/create-session.dto.tsindex 46414012a..85cf23576 100644--- a/src/modules/session/dto/create-session.dto.ts+++ b/src/modules/session/dto/create-session.dto.ts@@ -20,7 +20,7 @@ export class CreateSessionDto {@ApiPropertyOptional({description:'Session configuration. Only three keys are read: autoRejectCalls (boolean, default false, ' +- 'Baileys engine only) rejects incoming calls as soon as they ring — the call.received event is still emitted ' ++ 'Baileys engine only) rejects incoming calls as soon as they ring, and the call.received event is still emitted ' +'first; maxReconnectAttempts (0-20, default unlimited) caps consecutive reconnects and ' +'reconnectBaseDelay (1000-300000 ms, default 5000) sets the backoff base, both for the ' +"gateway's own reconnect only (on Baileys the engine retries a transient drop itself, with a " +diff --git a/src/modules/session/session-engine-controls.ts b/src/modules/session/session-engine-controls.tsindex 3304e7557..0ff60b001 100644--- a/src/modules/session/session-engine-controls.ts+++ b/src/modules/session/session-engine-controls.ts@@ -300,8 +300,8 @@ export class SessionEngineControls {let tornDown = await this.fences.teardownEngineSafely(id, engine, e => e.disconnect(), 'disconnect');if (!tornDown) {// The graceful disconnect threw or timed out, so the engine may be half-attached (a leaked- // Chromium process or a live socket). Escalate to the hard kill — the same forceDestroy()- // forceKill() uses for a wedged engine — before reporting the stop.+ // Chromium process or a live socket). Escalate to the hard kill, the same forceDestroy()+ // that forceKill() uses for a wedged engine, before reporting the stop.this.logger.warn(`Graceful disconnect failed for session ${session.name}; escalating to force-destroy`, {sessionId: id,action: 'stop_escalate_force_destroy',@@ -320,7 +320,7 @@ export class SessionEngineControls {throw new BadGatewayException({statusCode: HttpStatus.BAD_GATEWAY,message:- 'Session was stopped locally, but the engine teardown did not complete — the engine ' ++ 'Session was stopped locally, but the engine teardown did not complete: the engine ' +'process may still be running. Retry the stop; restart the node to reap a leaked process.',error: 'Bad Gateway',code: 'SESSION_STOP_INCOMPLETE',diff --git a/src/modules/session/session.service.spec.ts b/src/modules/session/session.service.spec.tsindex 1120f732d..dc3aa9b5b 100644--- a/src/modules/session/session.service.spec.ts+++ b/src/modules/session/session.service.spec.ts@@ -5262,8 +5262,9 @@ describe('SessionService', () => {// Regression guard for the WhatsApp Status feature: posting a status produces an own-send echo// that Baileys delivers as `messages.upsert` with `type: 'append'` (NOT 'notify'). The adapter's// handleMessagesUpsert recognises the echo by the id the status post recorded and skips it before- // processInboundMessage, so it never reaches the engine callbacks. This test pins the engine-neutral last-chance guard —- // `isStatusBroadcast` on both onMessageCreate and onMessage — so a future change can't silently+ // processInboundMessage, so it never reaches the engine callbacks. This test pins the+ // engine-neutral last-chance guard, `isStatusBroadcast` on both onMessageCreate and+ // onMessage, so a future change can't silently// leak a status echo to websockets, webhooks, or the message table. Asserts the full no-side-effect// contract (webhook dispatch + WS emit + DB insert) for completeness, even though the existing// isStatusBroadcast tests above already cover the dispatch-only slice.