Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(calls): correct the whatsapp-web.js call detection claim

Yudhi Armyndharis183d189d0fe4
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 031697b68..03e4c8d9d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -30,7 +30,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### 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.
+- The docs, the README, the OpenAPI field descriptions and the dashboard's auto-reject hint mark call rejection, `autoRejectCalls` and the call outcome events as Baileys only, and `call.received` as not reliable on whatsapp-web.js ([#1118](https://github.com/rmyndharis/OpenWA/discussions/1118)). Thanks @etondeengole for the report.
### Upgrade notes (behavior changes)
diff --git a/README.md b/README.md
index ba2ff1776..479b334ef 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 (Baileys only: whatsapp-web.js no longer detects a ringing call) |
+| Call Handling | ✅ | `call.received` events (not reliable on whatsapp-web.js), reject calls and per-session auto-reject (Baileys only) |
| 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 07f8176bf..65bc4363f 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 يُرسل قبل ذلك. يسري على المكالمة التالية — دون الحاجة إلى إعادة التشغيل. مع محرك 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.json
index f5a79dc3f..6e38e5792 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. Nur mit der Baileys-Engine: whatsapp-web.js erkennt klingelnde Anrufe nicht mehr."
+ "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.json
index f4f705639..c81058bde 100644
--- a/dashboard/src/i18n/locales/en.json
+++ b/dashboard/src/i18n/locales/en.json
@@ -310,7 +310,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 no longer detects a ringing call."
+ "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/es.json b/dashboard/src/i18n/locales/es.json
index 02c48f452..2c708a375 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. Solo con el motor Baileys: whatsapp-web.js ya no detecta las llamadas mientras suenan."
+ "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 no puede rechazar llamadas."
},
"proxy": {
"title": "Proxy Configuration",
diff --git a/dashboard/src/i18n/locales/fr.json b/dashboard/src/i18n/locales/fr.json
index 839741e54..bd1692da4 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. Moteur Baileys uniquement : whatsapp-web.js ne détecte plus les appels pendant qu'ils sonnent."
+ "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.json
index bf815b40f..3c849d022 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 עדיין נשלח לפני כן. חל מהשיחה הבאה — ללא צורך בהפעלה מחדש. במנוע 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.json
index 700948661..973fd5c2f 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. Solo con il motore Baileys: whatsapp-web.js non rileva più le chiamate mentre squillano."
+ "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/ko.json b/dashboard/src/i18n/locales/ko.json
index 78cb3d4b0..2bb71309a 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 웹훅은 그전에 그대로 전송됩니다. 다음 통화부터 적용되며 재시작이 필요하지 않습니다. Baileys 엔진에서만 동작합니다. whatsapp-web.js에서는 더 이상 울리는 통화가 감지되지 않습니다."
+ "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 99df78fda..753e753a1 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. Somente no mecanismo Baileys: o whatsapp-web.js não detecta mais as chamadas enquanto tocam."
+ "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.json
index f79c6b941..eaa4a8984 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 వెబ్‌హుక్ మాత్రం ముందుగా పంపబడుతుంది. తదుపరి కాల్ నుండి వర్తిస్తుంది — పునఃప్రారంభం అవసరం లేదు. 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.json
index 192263890..967d256b0 100644
--- a/dashboard/src/i18n/locales/tr.json
+++ b/dashboard/src/i18n/locales/tr.json
@@ -310,7 +310,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 artık çalan aramaları algılamıyor."
+ "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.json
index 7f544081f..d67c61178 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 仍会先行触发。下一通来电起生效,无需重启。仅限 Baileys 引擎:whatsapp-web.js 已无法检测到正在响铃的来电。"
+ "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 67d131bcd..494a7f688 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 仍會先行觸發。下一通來電起生效,無需重新啟動。僅限 Baileys 引擎:whatsapp-web.js 已無法偵測到正在響鈴的來電。"
+ "autoRejectCallsHint": "來電響鈴後即時拒接。call.received webhook 仍會先行觸發。下一通來電起生效,無需重新啟動。僅限 Baileys 引擎:whatsapp-web.js 無法拒接來電。"
},
"proxy": {
"title": "Proxy Configuration",
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index e1006bb08..ebc3e8cdf 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -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 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.
+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` is dispatched by both engines but is not reliable on whatsapp-web.js: it fired there in a live test on 2026-09-17 and did not in one on 2026-08-10. See the per-event catalog below for engine scope.
#### GET /api/sessions/:sessionId/webhooks
@@ -6306,7 +6306,7 @@ 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.
+> **Call rejection and the call outcome events are Baileys only, and `call.received` is not reliable on whatsapp-web.js.** Both engines dispatch `call.received`, but on whatsapp-web.js it fired in a live test on 2026-09-17 and did not in one on 2026-08-10. whatsapp-web.js cannot reject a call: a rejection it sent did not stop the call from ringing in a live test, so `autoRejectCalls` has no effect there either. The caller id in `from` may be an `@lid` privacy id on either engine; resolve it with `GET /api/sessions/:sessionId/contacts/:contactId/phone`. `POST .../calls/link` works on both engines.
#### POST /api/sessions/:sessionId/calls/link
@@ -6873,7 +6873,7 @@ 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. **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.received` | An incoming voice/video call starts ringing. Dispatched by both engines, but **not reliable on whatsapp-web.js**: it fired in a live test on 2026-09-17 and did not in one on 2026-08-10 | `{ callId, from, isVideo, isGroup, timestamp }` — `callId` is the id to pass to `POST /sessions/:sessionId/calls/:callId/reject` (Baileys only). `from` may be an `@lid` privacy id on either engine; resolve it with `GET /api/sessions/:sessionId/contacts/:contactId/phone` |
| `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 |
diff --git a/docs/12-troubleshooting-faq.md b/docs/12-troubleshooting-faq.md
index 3b1b2ebf3..c59e00625 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 (Baileys only; payload: callId, from, isVideo, isGroup, timestamp)
+ - call.received # Incoming call ringing (not reliable on whatsapp-web.js; 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 3a0ffd6ed..50e8c649a 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). **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** |
+| Method | Signature | Description |
+| ------------ | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rejectCall` | `rejectCall(sessionId, callId)` | Reject a ringing incoming call (`callId` comes from the `call.received` event). **Baileys only**: whatsapp-web.js cannot reject a call. **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. **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** |
+| Method | Signature | Description |
+| ------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `reject_call` | `reject_call(session_id, call_id) -> SuccessResult` | Reject a ringing incoming call. **Baileys only**: whatsapp-web.js cannot reject a call. **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). **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** |
+| 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**: whatsapp-web.js cannot reject a call. **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 9254a2d83..f9b48d538 100644
--- a/docs/22-n8n-integration.md
+++ b/docs/22-n8n-integration.md
@@ -95,14 +95,17 @@ 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 ringing, **Baileys only** | Auto-reject + auto-reply bots |
+| `call.received` | Call ringing, not reliable on whatsapp-web.js | Auto-reject + auto-reply bots |
> [!NOTE]
-> 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`.
+> The three call-outcome events fire on Baileys only: whatsapp-web.js has no call-outcome event, so a
+> workflow triggered on `call.missed` never runs on a whatsapp-web.js session. `call.received` fires
+> on both engines but is not reliable on whatsapp-web.js: it fired in a live test on 2026-09-17 and
+> did not in one on 2026-08-10. Rejecting a call, the session's auto-reject setting included, is
+> Baileys only: a rejection sent by whatsapp-web.js did not stop the call from ringing in a live
+> test. Reliable call automation needs a gateway running `ENGINE_TYPE=baileys`. The caller in `from`
+> may be an `@lid` privacy id on either engine; resolve it with
+> `GET /api/sessions/{sessionId}/contacts/{contactId}/phone`.
#### How It Works
@@ -278,8 +281,9 @@ 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 any call trigger, `call.received` included, confirm the gateway runs Baileys: see the note
- under the trigger event table above
+6. For a call trigger, check the session's engine: the call-outcome events never fire on
+ whatsapp-web.js and `call.received` is not reliable there (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/openapi.json b/openapi.json
index 6704c07e9..2cb1d3861 100644
--- a/openapi.json
+++ b/openapi.json
@@ -10268,7 +10268,7 @@
"properties": {
"autoRejectCalls": {
"type": "boolean",
- "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.",
+ "description": "Auto-reject every incoming call as soon as it rings. Baileys engine only: whatsapp-web.js cannot reject a 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/modules/session/dto/session-config.dto.ts b/src/modules/session/dto/session-config.dto.ts
index f92c66eeb..97270713a 100644
--- a/src/modules/session/dto/session-config.dto.ts
+++ b/src/modules/session/dto/session-config.dto.ts
@@ -18,8 +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. Baileys engine only: whatsapp-web.js no ' +
- 'longer detects a ringing call. The call.received event is still ' +
+ 'Auto-reject every incoming call as soon as it rings. Baileys engine only: whatsapp-web.js cannot ' +
+ 'reject a 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,