Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(calls): mark call events and call rejection as Baileys only

Yudhi Armyndharis4810f30bd4cd
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 96cb11bab..69df15fb2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Live WebSocket sockets are re-validated against the API-key table once a minute, so a key deleted, revoked, expired or narrowed on another node or by a direct database write drops its sockets there too, and a socket that connected while its key was being revoked no longer keeps that authorization for the life of the connection ([#1625](https://github.com/rmyndharis/OpenWA/issues/1625)).
- A WebSocket subscribe whose socket is evicted while it is in flight no longer registers its rooms after the disconnect.
+### Documentation
+
+- The docs, the README, the OpenAPI field descriptions and the dashboard's auto-reject hint mark call events, call rejection and `autoRejectCalls` as Baileys only: on current WhatsApp Web builds whatsapp-web.js no longer detects a ringing call ([#1118](https://github.com/rmyndharis/OpenWA/discussions/1118)). Thanks @etondeengole for the report.
+
### Upgrade notes (behavior changes)
- PostgreSQL deployments: the data connection issues `SET TIME ZONE 'UTC'` per connection and verifies the result at boot. A deployment where that cannot hold (a pooler that drops session state) now fails to start, naming the effective zone; set the default instead with `ALTER DATABASE "<database>" SET TimeZone='UTC'`. SQLite deployments, and any gateway already running in UTC, are unaffected and no data moves.
diff --git a/README.md b/README.md
index 9e13c2e3f..ba2ff1776 100644
--- a/README.md
+++ b/README.md
@@ -129,7 +129,7 @@ For any deployment where ethical, legal, or regulatory compliance matters (healt
| ------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Groups API | ✅ | Create, manage, join (invite code), and configure groups |
| Profile Management | ✅ | Set own display name, about text, and profile picture |
-| Call Handling | ✅ | `call.received` events, reject calls, per-session auto-reject |
+| Call Handling | ✅ | `call.received` events, reject calls, per-session auto-reject (Baileys only: whatsapp-web.js no longer detects a ringing call) |
| Channels/Newsletter | ✅ | WhatsApp Channels support |
| Labels Management | ✅ | Organize chats with labels |
| Proxy Support | ✅ | Per-session proxy configuration |
diff --git a/dashboard/src/i18n/locales/ar.json b/dashboard/src/i18n/locales/ar.json
index 1a57514e9..887577931 100644
--- a/dashboard/src/i18n/locales/ar.json
+++ b/dashboard/src/i18n/locales/ar.json
@@ -316,7 +316,7 @@
"created": "تاريخ الإنشاء",
"lastActive": "آخر نشاط",
"autoRejectCalls": "الرفض التلقائي للمكالمات",
- "autoRejectCallsHint": "يتم رفض المكالمات الواردة فور رنينها. ولا يزال الويب هوك call.received يُرسل قبل ذلك. يسري على المكالمة التالية — دون الحاجة إلى إعادة التشغيل."
+ "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.json
index 36a154b8d..ad4baf541 100644
--- a/dashboard/src/i18n/locales/de.json
+++ b/dashboard/src/i18n/locales/de.json
@@ -305,7 +305,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."
+ "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 erkennt klingelnde Anrufe nicht mehr."
},
"proxy": {
"title": "Proxy Configuration",
diff --git a/dashboard/src/i18n/locales/en.json b/dashboard/src/i18n/locales/en.json
index 7b7e55bbc..5777f6ffc 100644
--- a/dashboard/src/i18n/locales/en.json
+++ b/dashboard/src/i18n/locales/en.json
@@ -309,7 +309,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."
+ "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 no longer detects a ringing call."
},
"proxy": {
"title": "Proxy Configuration",
diff --git a/dashboard/src/i18n/locales/es.json b/dashboard/src/i18n/locales/es.json
index 2dde5473d..8ea30e0d1 100644
--- a/dashboard/src/i18n/locales/es.json
+++ b/dashboard/src/i18n/locales/es.json
@@ -305,7 +305,7 @@
"created": "Creado",
"lastActive": "Última actividad",
"autoRejectCalls": "Rechazar llamadas automáticamente",
- "autoRejectCallsHint": "Las llamadas entrantes se rechazan en cuanto suenan. El webhook call.received se envía igualmente antes. Se aplica a la próxima llamada; no hace falta reiniciar."
+ "autoRejectCallsHint": "Las llamadas entrantes se rechazan en cuanto suenan. El webhook call.received se envía igualmente antes. Se aplica a la próxima llamada; no hace falta reiniciar. Solo con el motor Baileys: whatsapp-web.js ya no detecta las llamadas mientras suenan."
},
"proxy": {
"title": "Proxy Configuration",
diff --git a/dashboard/src/i18n/locales/fr.json b/dashboard/src/i18n/locales/fr.json
index 71979b553..1d7924b3d 100644
--- a/dashboard/src/i18n/locales/fr.json
+++ b/dashboard/src/i18n/locales/fr.json
@@ -305,7 +305,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."
+ "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 détecte plus les appels pendant qu'ils sonnent."
},
"proxy": {
"title": "Proxy Configuration",
diff --git a/dashboard/src/i18n/locales/he.json b/dashboard/src/i18n/locales/he.json
index 4a5fdae7c..063b4b834 100644
--- a/dashboard/src/i18n/locales/he.json
+++ b/dashboard/src/i18n/locales/he.json
@@ -312,7 +312,7 @@
"created": "נוצר בתאריך",
"lastActive": "פעילות אחרונה",
"autoRejectCalls": "דחיית שיחות אוטומטית",
- "autoRejectCallsHint": "שיחות נכנסות נדחות ברגע שהן מצלצלות. ה-webhook call.received עדיין נשלח לפני כן. חל מהשיחה הבאה — ללא צורך בהפעלה מחדש."
+ "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.json
index fcf56622b..af5e9f3e2 100644
--- a/dashboard/src/i18n/locales/it.json
+++ b/dashboard/src/i18n/locales/it.json
@@ -305,7 +305,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."
+ "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 rileva più le chiamate mentre squillano."
},
"proxy": {
"title": "Configurazione proxy",
diff --git a/dashboard/src/i18n/locales/ko.json b/dashboard/src/i18n/locales/ko.json
index 90f3d7220..d1ab2e8f2 100644
--- a/dashboard/src/i18n/locales/ko.json
+++ b/dashboard/src/i18n/locales/ko.json
@@ -305,7 +305,7 @@
"created": "생성일",
"lastActive": "마지막 활동",
"autoRejectCalls": "통화 자동 거절",
- "autoRejectCallsHint": "수신 통화가 울리는 즉시 거절됩니다. call.received 웹훅은 그전에 그대로 전송됩니다. 다음 통화부터 적용되며 재시작이 필요하지 않습니다."
+ "autoRejectCallsHint": "수신 통화가 울리는 즉시 거절됩니다. call.received 웹훅은 그전에 그대로 전송됩니다. 다음 통화부터 적용되며 재시작이 필요하지 않습니다. Baileys 엔진에서만 동작합니다. whatsapp-web.js에서는 더 이상 울리는 통화가 감지되지 않습니다."
},
"proxy": {
"title": "Proxy Configuration",
diff --git a/dashboard/src/i18n/locales/pt-BR.json b/dashboard/src/i18n/locales/pt-BR.json
index 4c670f5f0..8af288f0e 100644
--- a/dashboard/src/i18n/locales/pt-BR.json
+++ b/dashboard/src/i18n/locales/pt-BR.json
@@ -305,7 +305,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."
+ "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 detecta mais as chamadas enquanto tocam."
},
"proxy": {
"title": "Proxy Configuration",
diff --git a/dashboard/src/i18n/locales/te.json b/dashboard/src/i18n/locales/te.json
index d3130e230..ea37e5b52 100644
--- a/dashboard/src/i18n/locales/te.json
+++ b/dashboard/src/i18n/locales/te.json
@@ -305,7 +305,7 @@
"created": "సృష్టించబడింది",
"lastActive": "చివరిసారి యాక్టివ్",
"autoRejectCalls": "కాల్‌లను ఆటోమేటిక్‌గా తిరస్కరించు",
- "autoRejectCallsHint": "ఇన్‌కమింగ్ కాల్‌లు మోగిన వెంటనే తిరస్కరించబడతాయి. call.received వెబ్‌హుక్ మాత్రం ముందుగా పంపబడుతుంది. తదుపరి కాల్ నుండి వర్తిస్తుంది — పునఃప్రారంభం అవసరం లేదు."
+ "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.json
index a53d3bd24..6464dab4a 100644
--- a/dashboard/src/i18n/locales/tr.json
+++ b/dashboard/src/i18n/locales/tr.json
@@ -309,7 +309,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."
+ "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 artık çalan aramaları algılamıyor."
},
"proxy": {
"title": "Proxy Configuration",
diff --git a/dashboard/src/i18n/locales/zh-CN.json b/dashboard/src/i18n/locales/zh-CN.json
index 4d719efb6..9ea6f5781 100644
--- a/dashboard/src/i18n/locales/zh-CN.json
+++ b/dashboard/src/i18n/locales/zh-CN.json
@@ -305,7 +305,7 @@
"created": "创建时间",
"lastActive": "上次活跃",
"autoRejectCalls": "自动拒接来电",
- "autoRejectCallsHint": "来电响铃后立即拒接。call.received webhook 仍会先行触发。下一通来电起生效,无需重启。"
+ "autoRejectCallsHint": "来电响铃后立即拒接。call.received webhook 仍会先行触发。下一通来电起生效,无需重启。仅限 Baileys 引擎:whatsapp-web.js 已无法检测到正在响铃的来电。"
},
"proxy": {
"title": "Proxy Configuration",
diff --git a/dashboard/src/i18n/locales/zh-HK.json b/dashboard/src/i18n/locales/zh-HK.json
index 65cbca474..8a625621c 100644
--- a/dashboard/src/i18n/locales/zh-HK.json
+++ b/dashboard/src/i18n/locales/zh-HK.json
@@ -305,7 +305,7 @@
"created": "建立時間",
"lastActive": "上次活躍",
"autoRejectCalls": "自動拒接來電",
- "autoRejectCallsHint": "來電響鈴後即時拒接。call.received webhook 仍會先行觸發。下一通來電起生效,無需重新啟動。"
+ "autoRejectCallsHint": "來電響鈴後即時拒接。call.received webhook 仍會先行觸發。下一通來電起生效,無需重新啟動。僅限 Baileys 引擎:whatsapp-web.js 已無法偵測到正在響鈴的來電。"
},
"proxy": {
"title": "Proxy Configuration",
diff --git a/docs/05-database-design.md b/docs/05-database-design.md
index 4d04ee131..9f44ecee7 100644
--- a/docs/05-database-design.md
+++ b/docs/05-database-design.md
@@ -377,7 +377,7 @@ clears it, and so does a gateway restart.
| ---------------------- | --------- | ------------------------------------------------------------------------ |
| `maxReconnectAttempts` | unlimited | Reconnect attempt cap, clamped to 0–20 (`0` disables reconnect entirely) |
| `reconnectBaseDelay` | `5000` ms | Base delay of the reconnect backoff, clamped to 1000–300000 ms |
-| `autoRejectCalls` | `false` | Auto-reject an incoming call as soon as it rings |
+| `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 with
`PATCH /api/sessions/{sessionId}/config` — no restart, and no re-scan of the QR. The patch merges, so a key
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index 144711064..d2b1f9306 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -323,7 +323,7 @@ and therefore apply on the next start, leaving a reconnect sequence already in f
| Field | Type | Constraints | Description |
| ---------------------- | ------- | ------------------------- | ------------------------------------------------------------------ |
-| `autoRejectCalls` | boolean | — | Auto-reject every incoming call as soon as it rings |
+| `autoRejectCalls` | boolean | — | Auto-reject every incoming call as soon as it rings (Baileys only) |
| `maxReconnectAttempts` | number | integer, 0–20 | Reconnect attempt cap (`0` disables reconnect; `null` = unlimited) |
| `reconnectBaseDelay` | number | integer, 1000–300000 (ms) | Base delay of the reconnect backoff |
@@ -4380,7 +4380,7 @@ Webhooks are configured per session and managed under `/api/sessions/:sessionId/
Two fields — `secret` and `headers` — are **write-only**: they are accepted on create/update but are never returned by any webhook route (the response DTO has no `@Expose` for them, so `fromEntity` drops them). `GET /api/infra/export-data` also omits both from its `webhooks` rows, so a backup no longer carries webhook credentials — a restored webhook comes back unsigned (`secret` null, `headers` `{}`) until you set them again. The `secret` is used to compute the `X-OpenWA-Signature: sha256=<hex>` HMAC-SHA256 header on deliveries.
-The `events` array accepts these members plus the `*` wildcard: `message.received`, `message.sent`, `message.ack`, `message.failed`, `message.revoked`, `message.reaction`, `message.edited`, `session.status`, `session.qr`, `session.authenticated`, `session.disconnected`, `session.reconnect_loop`, `session.restriction`, `presence.update`, `call.accepted`, `call.rejected`, `call.missed`, `group.join`, `group.leave`, `group.update`, `group.join_request`, `call.received`, `status.received`. All of them are actively dispatched by at least one engine — none is a reserved placeholder. Four are **Baileys only**, because whatsapp-web.js produces no callback behind them: `presence.update` (its prerequisite `POST .../presence/subscribe` answers `501` there, so this one announces itself) and `call.accepted` / `call.rejected` / `call.missed` (whatsapp-web.js sees a call ring but never its outcome, so these three are accepted on subscribe and then simply never fire). See the per-event catalog below for engine scope.
+The `events` array accepts these members plus the `*` wildcard: `message.received`, `message.sent`, `message.ack`, `message.failed`, `message.revoked`, `message.reaction`, `message.edited`, `session.status`, `session.qr`, `session.authenticated`, `session.disconnected`, `session.reconnect_loop`, `session.restriction`, `presence.update`, `call.accepted`, `call.rejected`, `call.missed`, `group.join`, `group.leave`, `group.update`, `group.join_request`, `call.received`, `status.received`. All of them are actively dispatched by at least one engine — none is a reserved placeholder. Four are **Baileys only**, because whatsapp-web.js produces no callback behind them: `presence.update` (its prerequisite `POST .../presence/subscribe` answers `501` there, so this one announces itself) and `call.accepted` / `call.rejected` / `call.missed` (whatsapp-web.js has no call-outcome callback, so these three are accepted on subscribe and then simply never fire). `call.received` has a whatsapp-web.js callback, but on current WhatsApp Web builds that library no longer detects a ringing call, so in practice it fires on Baileys only too. See the per-event catalog below for engine scope.
#### GET /api/sessions/:sessionId/webhooks
@@ -6306,6 +6306,8 @@ repeat.
Incoming-call management. A `call.received` webhook/socket event (§6.6) announces an incoming ringing call and carries the `callId` used below.
+> **Call events and call rejection are Baileys only.** On current WhatsApp Web builds whatsapp-web.js no longer detects a ringing call. A whatsapp-web.js session emits no `call.*` event, so it never has a `callId` to reject and `autoRejectCalls` has no effect. `POST .../calls/link` works on both engines.
+
#### POST /api/sessions/:sessionId/calls/link
Generate a shareable WhatsApp call link.
@@ -6363,7 +6365,7 @@ Reject a currently ringing incoming call. Only a live call can be rejected — t
**Errors:** `400` session is not started · `401` missing/invalid `X-API-Key` · `403` key lacks OPERATOR role · `404` call not found or no longer ringing · `409` conflict or engine not ready (retryable) · `503` session not ready or dependency unavailable (retryable)
-> **Auto-reject per session.** Set `"config": { "autoRejectCalls": true }` when creating a session to have the server reject every incoming call automatically — the `call.received` event is still dispatched first, so automations keep full visibility.
+> **Auto-reject per session.** Set `"config": { "autoRejectCalls": true }` when creating a session to have the server reject every incoming call automatically — the `call.received` event is still dispatched first, so automations keep full visibility. Baileys only; see the note at the top of this section.
### 6.4.15 Media conversion (opt-in)
@@ -6870,8 +6872,8 @@ These are the events OpenWA actually emits. A webhook is registered with an `eve
| `group.leave` | Participant(s) leave or are removed from a group | `{ groupId, actorId?, participantIds, timestamp }` |
| `group.update` | Group metadata changes (subject, description, announce/locked settings) | `{ groupId, actorId?, participantIds, changes?, timestamp }` — `changes` carries only the fields that changed: `subject?`, `description?`, `announce?`, `locked?` |
| `group.join_request` | Someone asked to join a group this session administers (join-approval mode on) | `{ groupId, actorId?, participantIds, timestamp }` — `participantIds` are the users asking to join; `actorId` is who created the request when the engine reports one (differs from the requester on a non-admin add). Act on it via `GET/POST .../groups/:groupId/membership-requests[...]` **Baileys caveat**: the library (7.0.0-rc13) emits this only for non-admin-add requests — an invite-link self-request may produce no event there (upstream TODO); the membership-requests list endpoint still reports it. |
-| `call.received` | An incoming voice/video call starts ringing | `{ callId, from, isVideo, isGroup, timestamp }` — `callId` is the id to pass to `POST /sessions/:sessionId/calls/:callId/reject` |
-| `call.accepted` / `call.rejected` / `call.missed` | A ringing call ended — answered, declined, or never picked up. **Baileys only**: whatsapp-web.js hooks the call collection's insert and sees no status at all, so it can report the ring but never its outcome | `{ sessionId, callId, from, outcome, isVideo, isGroup, timestamp }` — `callId` matches the `call.received` that preceded it, so the pair can be correlated. The engines report _what_ happened, never _who_ did it: an accept can come from any linked device. An outcome is only sent for a call this session saw ring, and offline-replayed signalling for calls that ended while disconnected is dropped. WhatsApp's `terminate` is deliberately unmapped — it covers both a caller hanging up before answer and either side ending an answered call, with nothing to tell them apart |
+| `call.received` | An incoming voice/video call starts ringing. **Baileys only** in practice: on current WhatsApp Web builds whatsapp-web.js no longer detects a ringing call | `{ callId, from, isVideo, isGroup, timestamp }` — `callId` is the id to pass to `POST /sessions/:sessionId/calls/:callId/reject` |
+| `call.accepted` / `call.rejected` / `call.missed` | A ringing call ended — answered, declined, or never picked up. **Baileys only**: whatsapp-web.js emits no call-outcome event | `{ sessionId, callId, from, outcome, isVideo, isGroup, timestamp }` — `callId` matches the `call.received` that preceded it, so the pair can be correlated. The engines report _what_ happened, never _who_ did it: an accept can come from any linked device. An outcome is only sent for a call this session saw ring, and offline-replayed signalling for calls that ended while disconnected is dropped. WhatsApp's `terminate` is deliberately unmapped — it covers both a caller hanging up before answer and either side ending an answered call, with nothing to tell them apart |
| `status.received` | A contact posts a status/story (opt-in — see below) | `{ sessionId, statusId, contact: { id, name?, pushName? }, type, caption?, hasMedia, mediaOmitted, omitReason?, postedAt, expiresAt }` — `statusId` is the store's `id` (usable with the status endpoints below); `postedAt`/`expiresAt` are epoch **milliseconds** (unlike the epoch-seconds convention for message timestamps), matching the `GET /status` store's own `Date`-backed fields |
> **`status.received` is opt-in and carries no media blob.** Unlike every other event above, `status.received` is only delivered to a webhook whose `events` list explicitly includes `"status.received"` (or `"*"`) — registering for other events does not implicitly subscribe you to it. The payload never embeds media bytes: when `hasMedia` is `true`, fetch the file separately via `GET /api/sessions/:sessionId/status/:statusId/media`. Your own posted statuses never trigger this event — only inbound stories from contacts (an own-send echo is dropped before ingest).
diff --git a/docs/12-troubleshooting-faq.md b/docs/12-troubleshooting-faq.md
index 0d695ffcb..3b1b2ebf3 100644
--- a/docs/12-troubleshooting-faq.md
+++ b/docs/12-troubleshooting-faq.md
@@ -1333,7 +1333,7 @@ available_events:
- group.join_request # Someone asked to join a group this session administers
# Calls
- - call.received # Incoming call ringing (payload: callId, from, isVideo, isGroup, timestamp)
+ - call.received # Incoming call ringing (Baileys only; payload: callId, from, isVideo, isGroup, timestamp)
```
**Q: Webhook payload format?**
diff --git a/docs/18-sdk-design.md b/docs/18-sdk-design.md
index 2fe7580b1..3a0ffd6ed 100644
--- a/docs/18-sdk-design.md
+++ b/docs/18-sdk-design.md
@@ -327,10 +327,10 @@ Media bodies share the `SendMediaRequest` shape: `{ chatId, url? | base64?, mime
#### `calls`
-| Method | Signature | Description |
-| ------------ | ------------------------------- | -------------------------------------------------------------------------------------------- |
-| `rejectCall` | `rejectCall(sessionId, callId)` | Reject a ringing incoming call (`callId` comes from the `call.received` event). **OPERATOR** |
-| `createLink` | `createLink(sessionId, body)` | Create a shareable WhatsApp call link (`startTime` is epoch MILLISECONDS). **OPERATOR** |
+| Method | Signature | Description |
+| ------------ | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rejectCall` | `rejectCall(sessionId, callId)` | Reject a ringing incoming call (`callId` comes from the `call.received` event). **Baileys only** in practice: a whatsapp-web.js session never learns a `callId`. **OPERATOR** |
+| `createLink` | `createLink(sessionId, body)` | Create a shareable WhatsApp call link (`startTime` is epoch MILLISECONDS). **OPERATOR** |
#### `media`
@@ -696,10 +696,10 @@ Resources are accessed as properties on the client (e.g. `client.messages`). All
#### `client.calls`
-| Method | Signature | Description |
-| ------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------- |
-| `reject_call` | `reject_call(session_id, call_id) -> SuccessResult` | Reject a ringing incoming call. **OPERATOR** |
-| `create_link` | `create_link(session_id, body) -> CallLinkResponse` | Create a shareable WhatsApp call link (`startTime` is epoch MILLISECONDS). **OPERATOR** |
+| Method | Signature | Description |
+| ------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `reject_call` | `reject_call(session_id, call_id) -> SuccessResult` | Reject a ringing incoming call. **Baileys only** in practice: a whatsapp-web.js session never learns a `callId`. **OPERATOR** |
+| `create_link` | `create_link(session_id, body) -> CallLinkResponse` | Create a shareable WhatsApp call link (`startTime` is epoch MILLISECONDS). **OPERATOR** |
#### `client.media`
@@ -1040,10 +1040,10 @@ All payloads are associative arrays; all listed methods are synchronous and retu
#### `calls`
-| Method | Signature | Description |
-| ------------ | ------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
-| `rejectCall` | `rejectCall(string $sessionId, string $callId): array` | Reject a ringing incoming call (404 when it is not found or no longer ringing). **OPERATOR** |
-| `createLink` | `createLink(string $sessionId, array $body): array` | Create a shareable WhatsApp call link (`startTime` is epoch MILLISECONDS). **OPERATOR** |
+| Method | Signature | Description |
+| ------------ | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rejectCall` | `rejectCall(string $sessionId, string $callId): array` | Reject a ringing incoming call (404 when it is not found or no longer ringing). **Baileys only** in practice: a whatsapp-web.js session never learns a `callId`. **OPERATOR** |
+| `createLink` | `createLink(string $sessionId, array $body): array` | Create a shareable WhatsApp call link (`startTime` is epoch MILLISECONDS). **OPERATOR** |
#### `media`
diff --git a/docs/22-n8n-integration.md b/docs/22-n8n-integration.md
index 5d17a6877..9254a2d83 100644
--- a/docs/22-n8n-integration.md
+++ b/docs/22-n8n-integration.md
@@ -95,13 +95,14 @@ Start workflows when WhatsApp events occur.
| `group.leave` | Participant(s) left a group | Churn tracking |
| `group.update` | Group subject/description/settings changed | Group administration |
| `group.join_request` | Someone asked to join an administered group | Auto-approve/vet join requests |
-| `call.received` | Incoming call started ringing | Auto-reject + auto-reply bots |
+| `call.received` | Incoming call ringing, **Baileys only** | Auto-reject + auto-reply bots |
> [!NOTE]
-> The three call-outcome events fire on Baileys only. whatsapp-web.js hooks the call collection's
-> insert and sees no status at all, so it can report the ring but never how the call ended — a
-> workflow triggered on `call.missed` will simply never run on a whatsapp-web.js session.
-> `call.received` fires on both engines.
+> Call events fire on Baileys only. whatsapp-web.js has no call-outcome event, and on current
+> WhatsApp Web builds it no longer detects a ringing call either, so a workflow triggered on
+> `call.received`, `call.missed` or any other call event never runs on a whatsapp-web.js session, and
+> the session's auto-reject setting has nothing to act on. Call automation needs a gateway running
+> `ENGINE_TYPE=baileys`.
#### How It Works
@@ -277,8 +278,8 @@ Always use the correct format for chat IDs:
3. Verify n8n webhook URL is accessible from OpenWA server
4. Check firewall/proxy settings
5. Ensure session is connected and active
-6. For a call-outcome trigger, confirm the session runs Baileys — see the note under the trigger
- event table above
+6. For any call trigger, `call.received` included, confirm the gateway runs Baileys: see the note
+ under the trigger event table above
7. Ask OpenWA which side dropped the event:
`GET /api/webhooks/delivery-failures?sessionId={sessionId}` (ADMIN key). A row means OpenWA
delivered and n8n rejected it; an empty list means the event never reached delivery at all
diff --git a/docs/29-engine-capability-matrix.md b/docs/29-engine-capability-matrix.md
index 5aa06c8d0..04b2ce36f 100644
--- a/docs/29-engine-capability-matrix.md
+++ b/docs/29-engine-capability-matrix.md
@@ -880,6 +880,13 @@ adapter boundary — none silently stubs.
✅ means works end-to-end — but these rows carry behavioral differences worth knowing:
+- **`rejectCall` (wwjs) is ✅ because the adapter implements it, not because it can succeed.** On
+ current WhatsApp Web builds whatsapp-web.js 1.34.7 no longer fires its `call` event for a ringing
+ call: it hooks the internal map of WhatsApp Web's call collection, and real calls no longer pass
+ through it (measured live on OpenWA 0.14.4 on 2026-08-10, with Baileys firing `call.received` and
+ `call.rejected` on the same bench). A whatsapp-web.js session therefore emits no `call.*` event,
+ never learns a `callId` to reject, and ignores the `autoRejectCalls` session setting.
+ `createCallLink` is unaffected.
- **`postTextStatus` / `postImageStatus` / `postVideoStatus` / `postVoiceStatus` (wwjs).**
whatsapp-web.js has no status-recipient argument, so `StatusPostOptions.recipients` is **not
honored** — the post broadcasts to the account's status-privacy audience (a one-time warning is
@@ -890,10 +897,10 @@ adapter boundary — none silently stubs.
`sendAudioMessage`, `sendDocumentMessage` and `sendStickerMessage` are ✅ on wwjs for chats and
groups, but a `<id>@newsletter` recipient throws `ChannelMediaNotSupportedError` (a
`NotImplementedException` → HTTP 501) at `ensureNotChannelRecipient`
- (`wwebjs-messaging.ts:354` for the media funnel, `:409` for stickers). whatsapp-web.js calls
+ (`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 are the one
- place where an engine difference does **not** show up as a per-row ❌ in 29.4.
+ 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 is
WebP, but they reach it differently and they do not accept the same inputs. whatsapp-web.js passes
`sendMediaAsSticker: true`, and `Util.formatToWebpSticker` converts `image/*` **and** `video/*`
diff --git a/openapi.json b/openapi.json
index 048a4d561..dd77ebc6e 100644
--- a/openapi.json
+++ b/openapi.json
@@ -10091,7 +10091,7 @@
},
"config": {
"type": "object",
- "description": "Session configuration. Only three keys are read: autoRejectCalls (boolean, default false) rejects incoming calls as soon as they ring — 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. Anything else is stored but ignored. All three can be changed later with PATCH /api/sessions/{sessionId}/config, without restarting the session.",
+ "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 first; maxReconnectAttempts (0-20, default unlimited) caps consecutive reconnects; and reconnectBaseDelay (1000-300000 ms, default 5000) sets the backoff base. Anything else is stored but ignored. All three can be changed later with PATCH /api/sessions/{sessionId}/config, without restarting the session.",
"example": {
"autoRejectCalls": false,
"maxReconnectAttempts": 5,
@@ -10242,7 +10242,7 @@
"properties": {
"autoRejectCalls": {
"type": "boolean",
- "description": "Whether incoming calls are auto-rejected",
+ "description": "Whether incoming calls are auto-rejected (Baileys engine only)",
"example": false
},
"maxReconnectAttempts": {
@@ -10268,7 +10268,7 @@
"properties": {
"autoRejectCalls": {
"type": "boolean",
- "description": "Auto-reject every incoming call as soon as it rings. The call.received event is still emitted first, so a webhook consumer sees the call regardless. Takes effect on the next incoming call — the session is not restarted.",
+ "description": "Auto-reject every incoming call as soon as it rings. Baileys engine only: whatsapp-web.js no longer detects a ringing call. The call.received event is still emitted first, so a webhook consumer sees the call regardless. Takes effect on the next incoming call — the session is not restarted.",
"example": true,
"nullable": true
},
diff --git a/src/engine/engine-capability-matrix.ts b/src/engine/engine-capability-matrix.ts
index 8b3dc93b9..245597a5a 100644
--- a/src/engine/engine-capability-matrix.ts
+++ b/src/engine/engine-capability-matrix.ts
@@ -302,7 +302,7 @@ export const CURATED_CAPABILITY_EXCEPTIONS: Record<string, MethodCapability> = {
wwjs: { status: 'supported' },
baileys: { status: 'supported' },
evidence:
- "wwjs Call.reject() (index.d.ts:2417) on the live Call cached from the client 'call' event (index.d.ts:643); baileys rejectCall(callId, callFrom) (Socket/messages-recv.d.ts:10) with the raw `from` JID cached from the 'offer' call event (Types/Call.d.ts)",
+ "wwjs Call.reject() (index.d.ts:2417) on the live Call cached from the client 'call' event (index.d.ts:643); baileys rejectCall(callId, callFrom) (Socket/messages-recv.d.ts:10) with the raw `from` JID cached from the 'offer' call event (Types/Call.d.ts). On current WhatsApp Web builds the wwjs 'call' event no longer fires for a ringing call (measured live on OpenWA 0.14.4 on 2026-08-10, Baileys firing call.received and call.rejected on the same bench), so the wwjs cache is never populated: the cell records the implemented method, and docs/29 29.7 carries the caveat",
},
sendCatalog: {
wwjs: { status: 'not-available', rootCause: 'library-limitation' },
diff --git a/src/modules/session/dto/create-session.dto.ts b/src/modules/session/dto/create-session.dto.ts
index 64d61d9d4..b73a66015 100644
--- a/src/modules/session/dto/create-session.dto.ts
+++ b/src/modules/session/dto/create-session.dto.ts
@@ -18,8 +18,8 @@ export class CreateSessionDto {
@ApiPropertyOptional({
description:
- 'Session configuration. Only three keys are read: autoRejectCalls (boolean, default false) ' +
- 'rejects incoming calls as soon as they ring — the call.received event is still emitted ' +
+ '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 ' +
'first; maxReconnectAttempts (0-20, default unlimited) caps consecutive reconnects; and ' +
'reconnectBaseDelay (1000-300000 ms, default 5000) sets the backoff base. Anything else is ' +
'stored but ignored. All three can be changed later with PATCH /api/sessions/{sessionId}/config, ' +
diff --git a/src/modules/session/dto/session-config.dto.ts b/src/modules/session/dto/session-config.dto.ts
index 3fa5306c0..f92c66eeb 100644
--- a/src/modules/session/dto/session-config.dto.ts
+++ b/src/modules/session/dto/session-config.dto.ts
@@ -18,7 +18,8 @@ import { ToStrictBoolean, ToStrictNumber } from '../../../common/utils/strict-bo
export class UpdateSessionConfigDto {
@ApiPropertyOptional({
description:
- 'Auto-reject every incoming call as soon as it rings. The call.received event is still ' +
+ 'Auto-reject every incoming call as soon as it rings. Baileys engine only: whatsapp-web.js no ' +
+ 'longer detects a ringing call. The call.received event is still ' +
'emitted first, so a webhook consumer sees the call regardless. Takes effect on the next ' +
'incoming call — the session is not restarted.',
example: true,
@@ -80,7 +81,7 @@ export class UpdateSessionConfigDto {
* actually do, including for legacy rows whose stored values fall outside the accepted range.
*/
export class SessionConfigResponseDto {
- @ApiProperty({ description: 'Whether incoming calls are auto-rejected', example: false })
+ @ApiProperty({ description: 'Whether incoming calls are auto-rejected (Baileys engine only)', example: false })
autoRejectCalls!: boolean;
@ApiProperty({