Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
feat(webhook): report poll votes as poll.vote (whatsapp-web.js)
laviniarochaprec8b226d3dd681
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 22bd75471..c9cddf452 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0### Added+- Report poll votes as a `poll.vote` webhook and WebSocket event on whatsapp-web.js: the poll, chat, voter, the option texts now selected (`[]` when the vote is cleared), the poll question when WhatsApp Web still holds the poll, and the time of the change; the JavaScript, Python, Go and Java SDKs list the event name. Until now a vote reached no consumer, so a poll sent with `send-poll` could not be read back.- Add Number Checker page in dashboard for single and bulk WhatsApp recipient pre-validation, in every dashboard language (#1865). Thanks @Purushotham-Prajapati-24.- Add the opt-in `message.receipt` event for per-recipient group and status receipts on Baileys, sent to the webhooks and `/events` subscribers that name it (#1748); the JavaScript, Python, Go and Java SDKs list the event name from SDK 0.7.0. Receipts are bounded per webhook: a quarter of `WEBHOOK_DISPATCH_CONCURRENCY` deliveries run at once, shared by a session's receipt webhooks, three quarters of `WEBHOOK_DISPATCH_MAX_QUEUED` events wait for each, and further receipts are dropped and counted in `openwa_webhook_delivery_failures_total`. Thanks @KGMA74, and @berodcdev for the request.- Record plugin install, update, uninstall, enable, disable, configuration and session activation changes in the audit log.diff --git a/dashboard/src/i18n/locales/ar.json b/dashboard/src/i18n/locales/ar.jsonindex eced8e7aa..b4d679bc9 100644--- a/dashboard/src/i18n/locales/ar.json+++ b/dashboard/src/i18n/locales/ar.json@@ -696,6 +696,7 @@"session.restriction": "عندما يقيّد WhatsApp الحساب أو يرفع قيدًا عنه","presence.update": "عندما تصبح محادثة مشترك فيها متصلة أو تكتب أو تغادر","event.response": "عندما يرد ضيف على دعوة حدث في واتساب (سأحضر، لن أحضر، ربما)",+ "poll.vote": "عندما يختار شخص خيارات في استطلاع أو يلغي اختيارها (whatsapp-web.js)","group.join": "عند انضمام مشاركين إلى مجموعة أو إضافتهم إليها","group.leave": "عند مغادرة مشاركين مجموعة أو إزالتهم منها","group.update": "عند تغيّر اسم مجموعة أو وصفها أو إعداداتها",diff --git a/dashboard/src/i18n/locales/de.json b/dashboard/src/i18n/locales/de.jsonindex 8b0dd7a5d..3b845c511 100644--- a/dashboard/src/i18n/locales/de.json+++ b/dashboard/src/i18n/locales/de.json@@ -671,6 +671,7 @@"session.restriction": "Wenn WhatsApp das Konto einschränkt oder eine Einschränkung aufhebt","presence.update": "Wenn ein abonnierter Chat online geht, tippt oder offline geht","event.response": "Wenn ein Gast auf eine WhatsApp-Veranstaltung antwortet (Zusage, Absage, Vielleicht)",+ "poll.vote": "Wenn jemand bei einer Umfrage Optionen auswählt oder abwählt (whatsapp-web.js)","group.join": "Wenn Teilnehmer einer Gruppe beitreten oder hinzugefügt werden","group.leave": "Wenn Teilnehmer eine Gruppe verlassen oder entfernt werden","group.update": "Wenn sich Name, Beschreibung oder Einstellungen einer Gruppe ändern",diff --git a/dashboard/src/i18n/locales/en.json b/dashboard/src/i18n/locales/en.jsonindex 25721c7e2..a8a99fbcd 100644--- a/dashboard/src/i18n/locales/en.json+++ b/dashboard/src/i18n/locales/en.json@@ -671,6 +671,7 @@"session.restriction": "When WhatsApp restricts the account or lifts a restriction","presence.update": "When a subscribed chat comes online, types or goes offline","event.response": "When a guest answers a WhatsApp event invitation (going, not going, maybe)",+ "poll.vote": "When a voter selects or clears options on a poll (whatsapp-web.js)","group.join": "When participants join or are added to a group","group.leave": "When participants leave or are removed from a group","group.update": "When a group's name, description or settings change",diff --git a/dashboard/src/i18n/locales/es.json b/dashboard/src/i18n/locales/es.jsonindex ee16c0afb..4325f428d 100644--- a/dashboard/src/i18n/locales/es.json+++ b/dashboard/src/i18n/locales/es.json@@ -677,6 +677,7 @@"session.restriction": "Cuando WhatsApp restringe la cuenta o levanta una restricción","presence.update": "Cuando un chat suscrito se conecta, escribe o se desconecta","event.response": "Cuando un invitado responde a un evento de WhatsApp (asistirá, no asistirá, quizás)",+ "poll.vote": "Cuando alguien marca o desmarca opciones de una encuesta (whatsapp-web.js)","group.join": "Cuando participantes se unen a un grupo o son añadidos","group.leave": "Cuando participantes salen de un grupo o son eliminados","group.update": "Cuando cambian el nombre, la descripción o los ajustes de un grupo",diff --git a/dashboard/src/i18n/locales/fr.json b/dashboard/src/i18n/locales/fr.jsonindex 871645d3f..2286c0c98 100644--- a/dashboard/src/i18n/locales/fr.json+++ b/dashboard/src/i18n/locales/fr.json@@ -677,6 +677,7 @@"session.restriction": "Lorsque WhatsApp restreint le compte ou lève une restriction","presence.update": "Lorsqu'un chat suivi passe en ligne, écrit ou se déconnecte","event.response": "Lorsqu'un invité répond à un événement WhatsApp (participe, ne participe pas, peut-être)",+ "poll.vote": "Lorsqu'un participant coche ou décoche des options d'un sondage (whatsapp-web.js)","group.join": "Lorsque des participants rejoignent un groupe ou y sont ajoutés","group.leave": "Lorsque des participants quittent un groupe ou en sont retirés","group.update": "Lorsque le nom, la description ou les paramètres d'un groupe changent",diff --git a/dashboard/src/i18n/locales/he.json b/dashboard/src/i18n/locales/he.jsonindex 79436bc8a..ca94d1f3a 100644--- a/dashboard/src/i18n/locales/he.json+++ b/dashboard/src/i18n/locales/he.json@@ -684,6 +684,7 @@"session.restriction": "כאשר WhatsApp מגביל את החשבון או מסיר הגבלה","presence.update": "כאשר צ'אט במעקב מתחבר, מקליד או מתנתק","event.response": "כאשר אורח עונה להזמנה לאירוע בוואטסאפ (מגיע, לא מגיע, אולי)",+ "poll.vote": "כאשר מישהו בוחר או מבטל אפשרויות בסקר (whatsapp-web.js)","group.join": "כאשר משתתפים מצטרפים לקבוצה או מתווספים אליה","group.leave": "כאשר משתתפים עוזבים קבוצה או מוסרים ממנה","group.update": "כאשר השם, התיאור או ההגדרות של קבוצה משתנים",diff --git a/dashboard/src/i18n/locales/hi.json b/dashboard/src/i18n/locales/hi.jsonindex 191429076..909057a10 100644--- a/dashboard/src/i18n/locales/hi.json+++ b/dashboard/src/i18n/locales/hi.json@@ -671,6 +671,7 @@"session.restriction": "जब WhatsApp खाते को प्रतिबंधित करता है या प्रतिबंध हटाता है","presence.update": "जब सब्सक्राइब की गई चैट ऑनलाइन आती है, टाइप करती है या ऑफ़लाइन जाती है","event.response": "जब कोई मेहमान WhatsApp इवेंट के निमंत्रण का जवाब देता है (आ रहे हैं, नहीं आ रहे, शायद)",+ "poll.vote": "जब कोई पोल में विकल्प चुनता है या हटाता है (whatsapp-web.js)","group.join": "जब प्रतिभागी समूह में शामिल होते हैं या जोड़े जाते हैं","group.leave": "जब प्रतिभागी समूह छोड़ते हैं या हटाए जाते हैं","group.update": "जब किसी समूह का नाम, विवरण या सेटिंग्स बदलती हैं",diff --git a/dashboard/src/i18n/locales/id.json b/dashboard/src/i18n/locales/id.jsonindex 1a069edf8..38bc0b260 100644--- a/dashboard/src/i18n/locales/id.json+++ b/dashboard/src/i18n/locales/id.json@@ -671,6 +671,7 @@"session.restriction": "Saat WhatsApp membatasi akun atau mencabut pembatasan","presence.update": "Saat obrolan yang dilanggani online, mengetik atau offline","event.response": "Saat tamu menjawab undangan acara WhatsApp (hadir, tidak hadir, mungkin)",+ "poll.vote": "Saat seseorang memilih atau membatalkan opsi pada polling (whatsapp-web.js)","group.join": "Saat peserta bergabung atau ditambahkan ke grup","group.leave": "Saat peserta keluar atau dikeluarkan dari grup","group.update": "Saat nama, deskripsi atau pengaturan grup berubah",diff --git a/dashboard/src/i18n/locales/it.json b/dashboard/src/i18n/locales/it.jsonindex 2007e6fab..28e6da5a4 100644--- a/dashboard/src/i18n/locales/it.json+++ b/dashboard/src/i18n/locales/it.json@@ -677,6 +677,7 @@"session.restriction": "Quando WhatsApp limita l'account o rimuove una limitazione","presence.update": "Quando una chat seguita va online, scrive o va offline","event.response": "Quando un invitato risponde a un evento WhatsApp (partecipa, non partecipa, forse)",+ "poll.vote": "Quando qualcuno seleziona o deseleziona opzioni di un sondaggio (whatsapp-web.js)","group.join": "Quando dei partecipanti entrano in un gruppo o vengono aggiunti","group.leave": "Quando dei partecipanti lasciano un gruppo o vengono rimossi","group.update": "Quando cambiano il nome, la descrizione o le impostazioni di un gruppo",diff --git a/dashboard/src/i18n/locales/ko.json b/dashboard/src/i18n/locales/ko.jsonindex 3014cf6df..0e46e70d7 100644--- a/dashboard/src/i18n/locales/ko.json+++ b/dashboard/src/i18n/locales/ko.json@@ -671,6 +671,7 @@"session.restriction": "WhatsApp이 계정을 제한하거나 제한을 해제했을 때","presence.update": "구독한 채팅이 온라인이 되거나 입력 중이거나 오프라인이 되었을 때","event.response": "게스트가 WhatsApp 이벤트 초대에 응답했을 때 (참석, 불참, 미정)",+ "poll.vote": "누군가 투표에서 옵션을 선택하거나 해제했을 때 (whatsapp-web.js)","group.join": "참여자가 그룹에 참여하거나 추가되었을 때","group.leave": "참여자가 그룹을 나가거나 내보내졌을 때","group.update": "그룹 이름, 설명 또는 설정이 바뀌었을 때",diff --git a/dashboard/src/i18n/locales/pt-BR.json b/dashboard/src/i18n/locales/pt-BR.jsonindex e05965071..5db32b9b4 100644--- a/dashboard/src/i18n/locales/pt-BR.json+++ b/dashboard/src/i18n/locales/pt-BR.json@@ -677,6 +677,7 @@"session.restriction": "Quando o WhatsApp restringe a conta ou remove uma restrição","presence.update": "Quando um chat inscrito fica online, digita ou fica offline","event.response": "Quando um convidado responde a um evento do WhatsApp (vai, não vai, talvez)",+ "poll.vote": "Quando alguém marca ou desmarca opções de uma enquete (whatsapp-web.js)","group.join": "Quando participantes entram em um grupo ou são adicionados","group.leave": "Quando participantes saem de um grupo ou são removidos","group.update": "Quando o nome, a descrição ou as configurações de um grupo mudam",diff --git a/dashboard/src/i18n/locales/te.json b/dashboard/src/i18n/locales/te.jsonindex d28daecaf..e81a54e9c 100644--- a/dashboard/src/i18n/locales/te.json+++ b/dashboard/src/i18n/locales/te.json@@ -671,6 +671,7 @@"session.restriction": "WhatsApp ఖాతాను పరిమితం చేసినప్పుడు లేదా పరిమితిని తొలగించినప్పుడు","presence.update": "సబ్స్క్రైబ్ చేసిన చాట్ ఆన్లైన్కి వచ్చినప్పుడు, టైప్ చేస్తున్నప్పుడు లేదా ఆఫ్లైన్కి వెళ్ళినప్పుడు","event.response": "అతిథి WhatsApp ఈవెంట్ ఆహ్వానానికి స్పందించినప్పుడు (వస్తున్నారు, రావడం లేదు, బహుశా)",+ "poll.vote": "ఎవరైనా పోల్లో ఎంపికలను ఎంచుకున్నప్పుడు లేదా తీసివేసినప్పుడు (whatsapp-web.js)","group.join": "సభ్యులు గ్రూప్లో చేరినప్పుడు లేదా జోడించబడినప్పుడు","group.leave": "సభ్యులు గ్రూప్ నుండి నిష్క్రమించినప్పుడు లేదా తొలగించబడినప్పుడు","group.update": "గ్రూప్ పేరు, వివరణ లేదా సెట్టింగ్లు మారినప్పుడు",diff --git a/dashboard/src/i18n/locales/tr.json b/dashboard/src/i18n/locales/tr.jsonindex 1497e2b84..e9c00df6e 100644--- a/dashboard/src/i18n/locales/tr.json+++ b/dashboard/src/i18n/locales/tr.json@@ -671,6 +671,7 @@"session.restriction": "WhatsApp hesabı kısıtladığında veya bir kısıtlamayı kaldırdığında","presence.update": "Abone olunan bir sohbet çevrimiçi olduğunda, yazdığında veya çevrimdışı olduğunda","event.response": "Bir davetli bir WhatsApp etkinliğine yanıt verdiğinde (katılıyor, katılmıyor, belki)",+ "poll.vote": "Biri bir ankette seçenek işaretlediğinde veya kaldırdığında (whatsapp-web.js)","group.join": "Katılımcılar bir gruba katıldığında veya eklendiğinde","group.leave": "Katılımcılar bir gruptan ayrıldığında veya çıkarıldığında","group.update": "Bir grubun adı, açıklaması veya ayarları değiştiğinde",diff --git a/dashboard/src/i18n/locales/zh-CN.json b/dashboard/src/i18n/locales/zh-CN.jsonindex 9225bc3ab..ac6e2f1c8 100644--- a/dashboard/src/i18n/locales/zh-CN.json+++ b/dashboard/src/i18n/locales/zh-CN.json@@ -671,6 +671,7 @@"session.restriction": "WhatsApp 限制账号或解除限制时","presence.update": "已订阅的聊天上线、正在输入或下线时","event.response": "嘉宾回复 WhatsApp 活动邀请时(参加、不参加、可能参加)",+ "poll.vote": "有人在投票中选择或取消选项时(whatsapp-web.js)","group.join": "有成员加入或被添加到群组时","group.leave": "有成员退出或被移出群组时","group.update": "群组名称、描述或设置变化时",diff --git a/dashboard/src/i18n/locales/zh-HK.json b/dashboard/src/i18n/locales/zh-HK.jsonindex cea45b438..e984ce010 100644--- a/dashboard/src/i18n/locales/zh-HK.json+++ b/dashboard/src/i18n/locales/zh-HK.json@@ -671,6 +671,7 @@"session.restriction": "WhatsApp 限制帳戶或解除限制時","presence.update": "已訂閱的聊天上線、正在輸入或離線時","event.response": "嘉賓回覆 WhatsApp 活動邀請時(參加、不參加、可能參加)",+ "poll.vote": "有人在投票中選擇或取消選項時(whatsapp-web.js)","group.join": "有成員加入或被加入群組時","group.leave": "有成員退出或被移出群組時","group.update": "群組名稱、描述或設定變更時",diff --git a/dashboard/src/utils/webhookEvents.ts b/dashboard/src/utils/webhookEvents.tsindex bae127641..b546573ae 100644--- a/dashboard/src/utils/webhookEvents.ts+++ b/dashboard/src/utils/webhookEvents.ts@@ -19,6 +19,7 @@ export const availableEventNames = ['session.restriction','presence.update','event.response',+ 'poll.vote','group.join','group.leave','group.update',diff --git a/docs/03-system-architecture.md b/docs/03-system-architecture.mdindex ef3adfdd7..d6f2a88bf 100644--- a/docs/03-system-architecture.md+++ b/docs/03-system-architecture.md@@ -936,6 +936,7 @@ export interface EngineEventCallbacks {onMessageReaction?: (event: ReactionEvent) => void;onMessageEdited?: (message: EditedMessage) => void;onEventResponse?: (event: EventResponseEvent) => void; // an RSVP to a WhatsApp event; Baileys only+ onPollVote?: (event: PollVoteEvent) => void; // a voter's new selection on a poll; whatsapp-web.js onlyonGroupEvent?: (event: GroupEvent) => void; // kind selects group.join / group.leave / group.update / group.join_requestonCall?: (event: IncomingCallEvent) => void; // incoming call ringing; Baileys can rejectCall() while it ringsonHistoryMessages?: (messages: IncomingMessage[]) => void | Promise<IncomingMessage[] | void>; // bulk initial sync; persist, don't dispatchdiff --git a/docs/04-security-design.md b/docs/04-security-design.mdindex 357c066c0..ad53e53c7 100644--- a/docs/04-security-design.md+++ b/docs/04-security-design.md@@ -322,7 +322,7 @@ export class CreateWebhookDto {@IsArray()@ArrayMinSize(1)// The full WEBHOOK_EVENTS catalog (message.*, status.received, session.*, presence.update,- // event.response, group.*, call.*) plus '*' for subscribe-all.+ // event.response, poll.vote, group.*, call.*) plus '*' for subscribe-all.@IsIn([...WEBHOOK_EVENTS, '*'], { each: true })events?: string[];}diff --git a/docs/05-database-design.md b/docs/05-database-design.mdindex b266ed8c8..a7553c65a 100644--- a/docs/05-database-design.md+++ b/docs/05-database-design.md@@ -480,6 +480,7 @@ CREATE TABLE webhooks ("session.restriction","presence.update","event.response",+ "poll.vote","group.join","group.leave","group.update",diff --git a/docs/06-api-specification.md b/docs/06-api-specification.mdindex 57c1d1052..c5b3e5885 100644--- a/docs/06-api-specification.md+++ b/docs/06-api-specification.md@@ -4625,7 +4625,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.receipt`, `message.failed`, `message.revoked`, `message.reaction`, `message.edited`, `session.status`, `session.qr`, `session.authenticated`, `session.disconnected`, `session.reconnect_loop`, `session.restriction`, `presence.update`, `event.response`, `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. Six are **Baileys only**, because whatsapp-web.js produces no callback behind them: `message.receipt` (whatsapp-web.js has no per-recipient receipt event), `presence.update` (its prerequisite `POST .../presence/subscribe` answers `501` there, so this one announces itself), `event.response` (accepted on subscribe and never fired) 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). `message.receipt` is the one event a `*` subscription does not receive: it fires once per recipient, so it must be named explicitly. `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.+The `events` array accepts these members plus the `*` wildcard: `message.received`, `message.sent`, `message.ack`, `message.receipt`, `message.failed`, `message.revoked`, `message.reaction`, `message.edited`, `session.status`, `session.qr`, `session.authenticated`, `session.disconnected`, `session.reconnect_loop`, `session.restriction`, `presence.update`, `event.response`, `poll.vote`, `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. Six are **Baileys only**, because whatsapp-web.js produces no callback behind them: `message.receipt` (whatsapp-web.js has no per-recipient receipt event), `presence.update` (its prerequisite `POST .../presence/subscribe` answers `501` there, so this one announces itself), `event.response` (accepted on subscribe and never fired) 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). `message.receipt` is the one event a `*` subscription does not receive: it fires once per recipient, so it must be named explicitly. `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. One is **whatsapp-web.js only**: `poll.vote` (the Baileys adapter does not decrypt vote updates, so it is accepted on subscribe and never fires there). See the per-event catalog below for engine scope.#### GET /api/sessions/:sessionId/webhooks@@ -7188,6 +7188,7 @@ session.disconnectedsession.restrictionpresence.updateevent.response+poll.votegroup.joingroup.leavegroup.update@@ -7205,7 +7206,7 @@ A subscribe request whose `events` array contains no recognized name (after filt### Wildcards and scoping-- **Chat-restricted keys receive only events for `allowedChats`.** Message, presence and `event.response` events require `data.chatId`; group events require `data.groupId`. Persisted phone/LID aliases are matched at delivery time, including mappings learned after subscribing. An event without a resolvable chat is omitted. Account events, calls, statuses, QR codes, and `group.join_request` (it names people outside the allowed chats, as the membership-request routes do) are omitted even with `events: ["*"]`; a request containing only account events answers `FORBIDDEN_EVENTS`. These filters apply across Redis replicas. A changed chat authorization disconnects the socket on its next subscribe.+- **Chat-restricted keys receive only events for `allowedChats`.** Message, presence, `event.response` and `poll.vote` events require `data.chatId`; group events require `data.groupId`. Persisted phone/LID aliases are matched at delivery time, including mappings learned after subscribing. An event without a resolvable chat is omitted. Account events, calls, statuses, QR codes, and `group.join_request` (it names people outside the allowed chats, as the membership-request routes do) are omitted even with `events: ["*"]`; a request containing only account events answers `FORBIDDEN_EVENTS`. These filters apply across Redis replicas. A changed chat authorization disconnects the socket on its next subscribe.- **`sessionId: "*"`** subscribes to every session; **`events: ["*"]`** subscribes to every subscribable event except `message.receipt`, whose per-recipient volume makes it opt-in by name. They combine (e.g. `"*"` + `["*"]` = every wildcard-covered event of every session).- The API key is **re-validated on every `subscribe`** (not just at connect), so a key revoked or expired mid-connection is caught — the server replies `UNAUTHORIZED` and disconnects.- **Per-key session scope is enforced** against the fresh key: a key restricted via `allowedSessions` may NOT subscribe to `"*"` and may NOT subscribe to a session outside its allowlist — either is rejected with `FORBIDDEN_SESSION`. An unrestricted key (no `allowedSessions`) may subscribe to anything, including `"*"`.@@ -7276,6 +7277,7 @@ These are the events OpenWA actually emits. A webhook is registered with an `eve| `session.reconnect_loop` | Every 5th consecutive reconnect attempt is scheduled (attempt 5, 10, 15, …) — the session is failing to come back up | `{ sessionId, attempts, nextDelayMs }` || `presence.update` | A subscribed chat's presence changed — someone came online, started typing, or stopped. Only actual CHANGES are dispatched: WhatsApp repeats itself freely, and every repeat would otherwise be a delivery | `{ sessionId, chatId, participants: [{ id, state, lastSeen? }], groupOnlineCount? }` — `state` is `available`/`unavailable`/`composing`/`recording`/`paused`; `lastSeen` is epoch **seconds** and absent when the contact hides it. Requires `POST .../presence/subscribe` first, and Baileys — whatsapp-web.js cannot observe presence || `event.response` | A guest answered a WhatsApp event invitation (going, not going, maybe). **Baileys only**; see the payload note below | `{ sessionId, eventMessageId, chatId, responderId, contact?, fromMe, response, extraGuestCount?, eventName?, responseMessageId, timestamp }`. `response` is `going`/`not_going`/`maybe`/`unknown`; `timestamp` is epoch **seconds** on the guest's clock. Order a guest's answers by `timestamp`, not by delivery |+| `poll.vote` | A voter selected or cleared options on a poll. **whatsapp-web.js only**; see the payload note below | `{ sessionId, pollMessageId, chatId, voterId, selectedOptions, pollName?, timestamp }`. `selectedOptions` holds the option texts now selected, `[]` when the vote was cleared; `timestamp` is epoch **seconds** on the voter's clock. Order a voter's changes by `timestamp`, not by delivery || `session.restriction` | WhatsApp places a restriction on the account, or lifts one. Deduped: an unchanged restriction is not re-announced, and a lift is only sent when one was in force | `{ sessionId, active, kind, code, expiresAt }` — `active` is `false` for a lift and `kind`/`code` then describe the restriction that ended; `expiresAt` is an ISO timestamp or `null`. See `restriction` on the session response for the `kind` values || `session.status` | The session status transitions | `{ sessionId, status }` where `status` is one of `created` / `initializing` / `qr_ready` / `authenticating` / `ready` / `disconnected` / `action_required` / `failed` || `group.join` | Participant(s) are added to or join a group this session is in | `{ groupId, actorId?, participantIds, timestamp }`. `actorId` is the admin/inviter when known. **Baileys**: a session added to or joining a group reports only its own id in `participantIds` (members added with it are not listed) |@@ -7332,6 +7334,22 @@ Existing stored mappings from older releases have mixed origins, so an upgrade r>> WhatsApp encrypts every RSVP with a key derived from the event creation message, so only answers to events **this session received and still holds in its message store** can be reported: an event posted before the number was linked, or one evicted past `BAILEYS_MESSAGE_STORE_LIMIT`, yields no `event.response`. This covers events in groups and in 1:1 chats, with one known gap: in a 1:1 chat, an answer from the person who posted the event, whether the other person or this account answering its own event, cannot be decrypted (Baileys derives the event's creator from the chat partner's side of the chat) and is not reported. Answers given while the session was offline are reported when WhatsApp replays them on reconnect. Baileys merges the updates it receives within one short buffer window per event, so several answers to one event that arrive in the same window, even from different guests (the whole replay after a reconnect, or answers a fraction of a second apart live), arrive as the last one only. whatsapp-web.js accepts the subscription and never fires the event.+> **`poll.vote` reports poll votes (whatsapp-web.js only).** A poll (sent with [`send-poll`](#post-apisessionssessionidmessagessend-poll) or from the phone) arrives as an ordinary `message.received` or `message.sent` when it is posted. Each time a voter changes their selection, the whole new selection arrives as `poll.vote`:+>+> ```json+> {+> "sessionId": "8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a",+> "pollMessageId": "[email protected]_3EB0C767D26B8A3F1A2B",+> "chatId": "[email protected]",+> "voterId": "[email protected]",+> "selectedOptions": ["Done"],+> "pollName": "Did you finish the report?",+> "timestamp": 1786000000+> }+> ```+>+> `selectedOptions` are the option texts exactly as they appear on the poll, the same strings [`vote-poll`](#post-apisessionssessionidmessagesvote-poll) takes. It is the voter's whole current selection, not a delta: `[]` means they cleared their vote, and the event with the latest `timestamp` per `voterId` is the current state. Order by `timestamp` rather than by arrival. `pollName` is present only when WhatsApp Web still holds the poll creation message; without it whatsapp-web.js cannot name the options either, and an option it cannot name is left out of `selectedOptions`. Vote counts are not kept by the gateway: tally them from these events. Baileys accepts the subscription and never fires it.+> WhatsApp also sends a contact's edit, and a reaction in some chats, encrypted under a secret carried by the message it changes. On Baileys they are read with the stored copy of that message, so `message.edited` fires for a message **this session received** and `message.reaction` for one it **received or sent**, while its message store still holds it; an edit or reaction of one the store no longer holds (evicted past `BAILEYS_MESSAGE_STORE_LIMIT`, or from before the number was linked) is not delivered. An edit the account makes from its own phone to its own message is applied under the account's own id the same way, whether it arrives as a plain or as an encrypted edit. whatsapp-web.js gets both already decrypted from WhatsApp Web.> There is **no** `contact.update` event. `presence.update` is emitted only for chats you have subscribed to (see the presence-subscription endpoint); call outcomes are reported as `call.accepted`, `call.rejected` and `call.missed` alongside `call.received`.@@ -7416,6 +7434,7 @@ Every delivery includes:- `session.restriction`: `restr_{sessionId}_{kind}_{active}_{occurredAt}`- `presence.update`: `pres_{sessionId}_{chatId}_{hash(participants)}_{occurredAt}`- `event.response`: `rsvp_{sessionId}_{responseMessageId}` (every answer is its own message with its own id, so no `occurredAt` salt)+- `poll.vote`: `vote_{sessionId}_{pollMessageId}_{voterId}_{timestamp}` (each change of a selection carries the voter's own timestamp, so no `occurredAt` salt)- any other event (for example `status.received`): `evt_{event with . replaced by _}_{hash(data)}`Recurring lifecycle events (and `message.reaction` / `message.edited` / `presence.update`) carry the same content across occurrences — the same phone on every reconnect, a constant disconnect reason, a re-applied emoji, or editing the same message multiple times — so they are salted with an `occurredAt` timestamp captured **once per dispatch and reused across that dispatch's retries**. This gives distinct occurrences distinct keys while keeping retries of one occurrence stable. Message keys are scoped by `sessionId` because WhatsApp message ids are unique per account, not globally.diff --git a/docs/12-troubleshooting-faq.md b/docs/12-troubleshooting-faq.mdindex 782f2b71e..485415e1c 100644--- a/docs/12-troubleshooting-faq.md+++ b/docs/12-troubleshooting-faq.md@@ -1473,6 +1473,7 @@ available_events:- session.restriction # WhatsApp restricted the account, or lifted it (payload: sessionId, active, kind, code, expiresAt)- presence.update # A subscribed chat's presence changed (Baileys only; the subscribe route answers 501 on whatsapp-web.js; payload: sessionId, chatId, participants, groupOnlineCount)- event.response # A guest answered a WhatsApp event invitation (Baileys only; payload: sessionId, eventMessageId, chatId, responderId, response, responseMessageId, timestamp)+ - poll.vote # A voter selected or cleared options on a poll (whatsapp-web.js only; payload: sessionId, pollMessageId, chatId, voterId, selectedOptions, pollName, timestamp)- call.accepted # A ringing call was answered (Baileys only; payload: sessionId, callId, from, outcome, isVideo, isGroup, timestamp)- call.rejected # A ringing call was declined (Baileys only)- call.missed # A ringing call was never picked up (Baileys only)diff --git a/docs/22-n8n-integration.md b/docs/22-n8n-integration.mdindex c769137c6..3e7edfe40 100644--- a/docs/22-n8n-integration.md+++ b/docs/22-n8n-integration.md@@ -92,6 +92,7 @@ Start workflows when WhatsApp events occur.| `session.restriction` | WhatsApp restricted the account, or lifted it | Pausing outreach while an account is limited || `presence.update` | A watched chat's online/typing state changed | Live agent hand-off, presence-aware routing || `event.response` | A guest answered a WhatsApp event (Baileys) | RSVP and attendance tracking |+| `poll.vote` | A voter changed their poll answer (wwebjs) | Surveys, check-ins and approvals || `call.accepted` / `call.rejected` / `call.missed` | A ringing call ended — **Baileys only** | Missed-call follow-up, call logging || `group.join` | Participant(s) joined a group | Welcome messages || `group.leave` | Participant(s) left a group | Churn tracking |diff --git a/docs/29-engine-capability-matrix.md b/docs/29-engine-capability-matrix.mdindex 44cc9e98c..beace0388 100644--- a/docs/29-engine-capability-matrix.md+++ b/docs/29-engine-capability-matrix.md@@ -843,7 +843,7 @@ OpenWA consumes events by normalizing them into `EngineEventCallbacks`; anything| `message_ciphertext` | ✅ | | `media_uploaded` | ❌ || `message_ciphertext_failed` | ❌ | | `remote_session_saved` | ❌ || `call` | ✅ | | `unread_count` | ❌ candidate |-| `qr` | ✅ | | `vote_update` | ❌ candidate (poll-vote webhook) |+| `qr` | ✅ | | `vote_update` | ✅ || `ready` | ✅ | | `authenticated` | ✅ || `auth_failure` | ✅ | | `code` | ❌ — the pairing code is the return value of `requestPairingCode`, not an event || `disconnected` | ✅ | | `group_join` | ✅ |@@ -1051,7 +1051,7 @@ adapter sources — re-derive the same way when anything changes:4 internal wiring, 1 class plumbing, **35 ❌ not exposed** (27 real capabilities + 8session/transport settings that are not WhatsApp capabilities). The backlog is the ❌ rows minusthose 8 settings; 🔩 plumbing is correctly never exposed.-- Events: Baileys **34** (18 consumed / 16 dropped), wwjs **31** (17 consumed / 14 dropped).+- Events: Baileys **34** (18 consumed / 16 dropped), wwjs **31** (18 consumed / 13 dropped).- **0** capabilities in 29.5.3: every capability with first-class symbols on both libraries iseither wired or classified with evidence. Some are Baileys-only despite typed whatsapp-web.jssymbols: `createGroup`, whose injected evaluate reaches a page internal without `findImpl`;diff --git a/openapi.json b/openapi.jsonindex f93441757..8f71b60f6 100644--- a/openapi.json+++ b/openapi.json@@ -19493,6 +19493,7 @@"session.restriction","presence.update","event.response",+ "poll.vote","group.join","group.leave","group.update",@@ -19591,6 +19592,7 @@"session.restriction","presence.update","event.response",+ "poll.vote","group.join","group.leave","group.update",@@ -19692,6 +19694,7 @@"session.restriction","presence.update","event.response",+ "poll.vote","group.join","group.leave","group.update",diff --git a/sdk/go/client_test.go b/sdk/go/client_test.goindex 5aa6eb155..684dede98 100644--- a/sdk/go/client_test.go+++ b/sdk/go/client_test.go@@ -1220,6 +1220,7 @@ func TestWebhookEventWireValues(t *testing.T) {EventSessionRestriction: "session.restriction",EventPresenceUpdate: "presence.update",EventEventResponse: "event.response",+ EventPollVote: "poll.vote",EventCallAccepted: "call.accepted",EventCallRejected: "call.rejected",EventCallMissed: "call.missed",diff --git a/sdk/go/types_webhook.go b/sdk/go/types_webhook.goindex 81c680864..0e6baee26 100644--- a/sdk/go/types_webhook.go+++ b/sdk/go/types_webhook.go@@ -28,6 +28,7 @@ const (EventSessionRestriction WebhookEvent = "session.restriction"EventPresenceUpdate WebhookEvent = "presence.update"EventEventResponse WebhookEvent = "event.response"+ EventPollVote WebhookEvent = "poll.vote"EventCallAccepted WebhookEvent = "call.accepted"EventCallRejected WebhookEvent = "call.rejected"EventCallMissed WebhookEvent = "call.missed"diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/model/WebhookEvent.java b/sdk/java/src/main/java/com/rmyndharis/openwa/model/WebhookEvent.javaindex fd8a2a539..90c9aaaa2 100644--- a/sdk/java/src/main/java/com/rmyndharis/openwa/model/WebhookEvent.java+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/model/WebhookEvent.java@@ -40,6 +40,8 @@ public enum WebhookEvent {PRESENCE_UPDATE,@SerializedName("event.response")EVENT_RESPONSE,+ @SerializedName("poll.vote")+ POLL_VOTE,@SerializedName("call.accepted")CALL_ACCEPTED,@SerializedName("call.rejected")diff --git a/sdk/javascript/src/types.ts b/sdk/javascript/src/types.tsindex 40d1e0f75..0b6b85c53 100644--- a/sdk/javascript/src/types.ts+++ b/sdk/javascript/src/types.ts@@ -959,6 +959,7 @@ export type WebhookEvent =| 'session.restriction'| 'presence.update'| 'event.response'+ | 'poll.vote'| 'call.accepted'| 'call.rejected'| 'call.missed'diff --git a/sdk/python/openwa/types.py b/sdk/python/openwa/types.pyindex bf2cfd10a..e88abe776 100644--- a/sdk/python/openwa/types.py+++ b/sdk/python/openwa/types.py@@ -69,7 +69,7 @@ WebhookEvent = Literal["message.received", "message.sent", "message.ack", "message.receipt", "message.failed", "message.revoked","message.reaction", "message.edited", "session.status", "session.qr", "session.authenticated","session.disconnected", "session.reconnect_loop", "session.restriction", "presence.update",- "event.response", "group.join", "group.leave", "group.update", "group.join_request",+ "event.response", "poll.vote", "group.join", "group.leave", "group.update", "group.join_request","call.received", "status.received","call.accepted", "call.rejected", "call.missed","*",@@ -79,7 +79,7 @@ WebhookDeliveryEvent = Literal["message.received", "message.sent", "message.ack", "message.receipt", "message.failed", "message.revoked","message.reaction", "message.edited", "session.status", "session.qr", "session.authenticated","session.disconnected", "session.reconnect_loop", "session.restriction", "presence.update",- "event.response", "group.join", "group.leave", "group.update", "group.join_request",+ "event.response", "poll.vote", "group.join", "group.leave", "group.update", "group.join_request","call.received", "status.received","call.accepted", "call.rejected", "call.missed",]diff --git a/src/engine/adapters/whatsapp-web-js.adapter.spec.ts b/src/engine/adapters/whatsapp-web-js.adapter.spec.tsindex dab1d734d..de88d7a75 100644--- a/src/engine/adapters/whatsapp-web-js.adapter.spec.ts+++ b/src/engine/adapters/whatsapp-web-js.adapter.spec.ts@@ -3979,6 +3979,105 @@ describe('WhatsAppWebJsAdapter inbound media (MEDIA_DOWNLOAD_ENABLED=false)', ()});});+describe('WhatsAppWebJsAdapter vote_update (poll.vote)', () => {+ const wireVoteHandler = (): { onPollVote: jest.Mock; client: EventEmitter } => {+ const adapter = new WhatsAppWebJsAdapter({+ sessionId: 'sess-vote-test',+ sessionDataPath: './data/sessions',+ puppeteer: {},+ });+ const client = Object.assign(new EventEmitter(), {+ info: { wid: { _serialized: '[email protected]', user: '628123' }, pushname: 'Tester' },+ getState: jest.fn().mockResolvedValue(WAState.CONNECTED),+ pupPage: { evaluate: jest.fn().mockResolvedValue(true) },+ });+ (adapter as unknown as { client: unknown }).client = client;+ const onPollVote = jest.fn();+ (adapter as unknown as { callbacks: unknown }).callbacks = { onPollVote };+ (adapter as unknown as { lifecycle: WwebjsLifecycle }).lifecycle.setupEventHandlers();+ return { onPollVote, client };+ };++ // The shape `PollVote` builds: `voter` and `parentMsgKey` are raw page-context Wids, and+ // `parentMessage` a Message built from the poll creation message (or from nothing).+ const ownPoll = {+ id: { _serialized: '[email protected]_POLL1' },+ from: '[email protected]',+ to: '[email protected]',+ fromMe: true,+ pollName: 'Did you finish the report?',+ };+ const vote = (overrides: Record<string, unknown> = {}): Record<string, unknown> => ({+ voter: { _serialized: '[email protected]' },+ selectedOptions: [{ name: 'Done', localId: 0 }],+ interractedAtTs: 1786000000123,+ parentMessage: ownPoll,+ parentMsgKey: { _serialized: '[email protected]_POLL1', remote: { _serialized: '[email protected]' } },+ ...overrides,+ });++ it('maps a vote on a poll the account sent to the neutral event', () => {+ const { onPollVote, client } = wireVoteHandler();++ client.emit('vote_update', vote());++ expect(onPollVote).toHaveBeenCalledWith({+ pollMessageId: '[email protected]_POLL1',+ chatId: '[email protected]',+ voterId: '[email protected]',+ selectedOptions: ['Done'],+ pollName: 'Did you finish the report?',+ timestamp: 1786000000,+ });+ });++ it('takes the chat from the sender of a poll the account received in a group', () => {+ const { onPollVote, client } = wireVoteHandler();+ const groupPoll = { ...ownPoll, from: '[email protected]', to: '[email protected]', fromMe: false };++ client.emit('vote_update', vote({ parentMessage: groupPoll, voter: { _serialized: 'member@lid' } }));++ expect(onPollVote).toHaveBeenCalledWith(+ expect.objectContaining({ chatId: '[email protected]', voterId: 'member@lid' }),+ );+ });++ it('reports a cleared vote as an empty selection', () => {+ const { onPollVote, client } = wireVoteHandler();++ client.emit('vote_update', vote({ selectedOptions: [] }));++ expect(onPollVote).toHaveBeenCalledWith(expect.objectContaining({ selectedOptions: [] }));+ });++ it('falls back to the poll key when WhatsApp Web no longer holds the poll, leaving unnamed options out', () => {+ const { onPollVote, client } = wireVoteHandler();++ // Without the creation message, PollVote builds an empty Message and keeps only local option ids.+ client.emit(+ 'vote_update',+ vote({ parentMessage: {}, selectedOptions: [{ name: undefined, localId: 1 }], voter: { $1: '[email protected]' } }),+ );++ const event = (onPollVote.mock.calls as Array<[Record<string, unknown>]>)[0][0];+ expect(event).toEqual({+ pollMessageId: '[email protected]_POLL1',+ chatId: '[email protected]',+ voterId: '[email protected]',+ selectedOptions: [],+ timestamp: 1786000000,+ });+ expect(event).not.toHaveProperty('pollName');+ });++ it('logs and drops a malformed vote instead of throwing into the client', () => {+ const { onPollVote, client } = wireVoteHandler();++ expect(() => client.emit('vote_update', null)).not.toThrow();+ expect(onPollVote).not.toHaveBeenCalled();+ });+});+describe('WhatsAppWebJsAdapter message_reaction (id resolution across WA Web builds)', () => {const wireReactionHandler = (): { onMessageReaction: jest.Mock; client: EventEmitter } => {const adapter = new WhatsAppWebJsAdapter({diff --git a/src/engine/adapters/wwebjs-message-events.ts b/src/engine/adapters/wwebjs-message-events.tsindex 9a4cf04f5..ffa38cc02 100644--- a/src/engine/adapters/wwebjs-message-events.ts+++ b/src/engine/adapters/wwebjs-message-events.ts@@ -6,6 +6,7 @@ import {type RevokedMessage,type ReactionEvent,type EditedMessage,+ type PollVoteEvent,} from '../interfaces/whatsapp-engine.interface';import { readWid, type SerializedWid } from '../types/whatsapp-web-js.types';import { buildEditedMessage, buildIncomingMessageBase, mapContactFields } from './message-mapper';@@ -52,7 +53,7 @@ interface Change {const NOT_KEPT: Processing = { handOver: () => true, end: () => undefined };/**- * Message-domain client events (message, message_create, ack, revoke, reaction, edit) extracted+ * Message-domain client events (message, message_create, ack, revoke, reaction, edit, vote) extracted* from the adapter's event wiring: pure mapping from wwebjs payloads to neutral events fired* through the engine callbacks. Connection-state events (qr/authenticated/ready/disconnected/* auth_failure) stay in the lifecycle module (./wwebjs-lifecycle) — they drive the lifecycle@@ -370,6 +371,38 @@ export function registerWwebjsMessageEvents(client: Client, host: WwebjsEngineHo}});+ client.on('vote_update', vote => {+ try {+ // `PollVote` assigns its keys straight through, like `Reaction`: `voter` is the raw sender Wid+ // (typed as a string upstream) and `parentMsgKey` (untyped upstream) the raw MsgKey of the poll,+ // so both are read with `readWid` (#747). `parentMessage` is built from the poll creation message+ // when WhatsApp Web holds it, and from nothing otherwise, so its fields may all be undefined; the+ // poll id and chat then come from `parentMsgKey`.+ const raw = vote as typeof vote & {+ voter: SerializedWid | string;+ parentMsgKey?: SerializedWid & { remote?: SerializedWid | string };+ };+ const poll = vote.parentMessage as Partial<Message> | undefined;+ const pollId = poll?.id as unknown as SerializedWid | undefined;+ const event: PollVoteEvent = {+ pollMessageId: readWid(pollId) ?? readWid(raw.parentMsgKey) ?? '',+ // Direction flag, as Message._getChatId (see message_revoke_everyone).+ chatId: (poll?.from ? (poll.fromMe ? poll.to : poll.from) : readWid(raw.parentMsgKey?.remote)) ?? '',+ voterId: readWid(raw.voter) ?? '',+ // Without the creation message whatsapp-web.js keeps only the local option ids, which no route+ // of this API takes, so an option it could not name is left out.+ selectedOptions: (vote.selectedOptions ?? [])+ .map(option => option.name)+ .filter((name): name is string => typeof name === 'string'),+ ...(poll?.pollName ? { pollName: poll.pollName } : {}),+ timestamp: Math.floor((Number(vote.interractedAtTs) || Date.now()) / 1000),+ };+ host.getCallbacks().onPollVote?.(event);+ } catch (error) {+ host.logger.error('Error processing vote_update', String(error));+ }+ });+client.on('message_edit', (message, newBody) => {try {// Raised for any change of a message's body or caption attribute, with `message` read after it. Users editdiff --git a/src/engine/interfaces/whatsapp-engine.interface.ts b/src/engine/interfaces/whatsapp-engine.interface.tsindex 9d9b9be3e..f35c40972 100644--- a/src/engine/interfaces/whatsapp-engine.interface.ts+++ b/src/engine/interfaces/whatsapp-engine.interface.ts@@ -698,6 +698,29 @@ export interface ReactionEvent {senderId: string;}+/**+ * A voter's current selection on a poll (the native poll sent with `send-poll` or from the phone).+ * WhatsApp sends the whole selection each time a voter changes it, so the latest `timestamp` per+ * `voterId` is the current state, and an empty `selectedOptions` means the voter cleared their vote.+ */+export interface PollVoteEvent {+ /** Id of the poll creation message the vote belongs to. */+ pollMessageId: string;+ /** Neutral id of the chat the poll was posted in. */+ chatId: string;+ /** Neutral id of the voter (the account itself when it voted from its phone). */+ voterId: string;+ /**+ * The option texts now selected, exactly as they appear on the poll (the same strings `vote-poll`+ * takes). An option the engine could not name is left out.+ */+ selectedOptions: string[];+ /** The poll's question, when the creation message is available to read it from. */+ pollName?: string;+ /** Unix seconds the voter changed the selection (sender clock). */+ timestamp: number;+}+/*** A group membership or metadata change, mapped at the adapter boundary to this neutral* shape so consumers never see engine-specific payloads:@@ -961,6 +984,11 @@ export interface EngineEventCallbacks {* decrypts the RSVP itself from the stored event creation message. whatsapp-web.js never fires it.*/onEventResponse?: (event: EventResponseEvent) => void;+ /**+ * Fired each time a voter changes their selection on a poll (consumers emit `poll.vote`).+ * whatsapp-web.js only: Baileys never fires it.+ */+ onPollVote?: (event: PollVoteEvent) => void;/*** Fired on group membership changes (join/leave), group metadata updates* (subject/description/announce/locked), and pending join requests. The `kind` selects thediff --git a/src/modules/events/dto/ws-messages.dto.ts b/src/modules/events/dto/ws-messages.dto.tsindex 59807bdc3..95b81fdff 100644--- a/src/modules/events/dto/ws-messages.dto.ts+++ b/src/modules/events/dto/ws-messages.dto.ts@@ -27,6 +27,7 @@ export const SUBSCRIBABLE_EVENTS = ['status.received','presence.update','event.response',+ 'poll.vote','call.accepted','call.rejected','call.missed',diff --git a/src/modules/events/events.gateway.ts b/src/modules/events/events.gateway.tsindex 434d914f0..ee9fd88db 100644--- a/src/modules/events/events.gateway.ts+++ b/src/modules/events/events.gateway.ts@@ -82,6 +82,7 @@ const CHAT_EVENTS = new Set(['group.update','presence.update','event.response',+ 'poll.vote',]);/**@@ -938,6 +939,11 @@ export class EventsGateway implements OnGatewayInit, OnGatewayConnection, OnGatethis.emitToRooms(sessionId, 'event.response', data);}+ /** Emit a voter's new selection on a poll (whatsapp-web.js only). Payload mirrors the `poll.vote` webhook. */+ emitPollVote(sessionId: string, data: Record<string, unknown>) {+ this.emitToRooms(sessionId, 'poll.vote', data);+ }+/*** Emit QR code update for a session. Scanning the QR links a device to the account, so it only* reaches keys that may read it over REST (OPERATOR and above).diff --git a/src/modules/session/session-engine-event-wiring.ts b/src/modules/session/session-engine-event-wiring.tsindex 7157eb10b..47bd9b27a 100644--- a/src/modules/session/session-engine-event-wiring.ts+++ b/src/modules/session/session-engine-event-wiring.ts@@ -296,6 +296,25 @@ export class SessionEngineEventWiring {host.eventsGateway.emitEventResponse(id, payload);void host.webhookService.dispatch(id, 'event.response', payload);},+ onPollVote: (event): void => {+ if (!host.isLiveEngine(id, engine)) return;+ if (!event.pollMessageId) {+ this.logger.warn('Ignoring poll vote without a poll message id', {+ sessionId: id,+ action: 'poll_vote_ignored',+ });+ return;+ }+ this.logger.debug(`Poll vote: ${event.selectedOptions.length} option(s) on ${event.pollMessageId}`, {+ sessionId: id,+ chatId: event.chatId,+ pollMessageId: event.pollMessageId,+ action: 'poll_vote',+ });+ const payload = { sessionId: id, ...event };+ host.eventsGateway.emitPollVote(id, payload);+ void host.webhookService.dispatch(id, 'poll.vote', payload);+ },onGroupEvent: (event): void => {if (!host.isLiveEngine(id, engine)) return;this.logger.debug(`Group event: ${event.kind} in ${event.groupId}`, {diff --git a/src/modules/session/session-poll-vote-wiring.spec.ts b/src/modules/session/session-poll-vote-wiring.spec.tsnew file mode 100644index 000000000..70776b358--- /dev/null+++ b/src/modules/session/session-poll-vote-wiring.spec.ts@@ -0,0 +1,68 @@+import { SessionEngineEventWiring, SessionEngineWiringHost } from './session-engine-event-wiring';+import { IWhatsAppEngine, PollVoteEvent } from '../../engine/interfaces/whatsapp-engine.interface';+import { createLogger } from '../../common/services/logger.service';++describe('poll.vote wiring', () => {+ const vote: PollVoteEvent = {+ pollMessageId: '[email protected]_POLL1',+ chatId: '[email protected]',+ voterId: '[email protected]',+ selectedOptions: ['Done'],+ pollName: 'Did you finish the report?',+ timestamp: 1786000000,+ };++ const setup = (live: boolean) => {+ const dispatch = jest.fn();+ const emitPollVote = jest.fn();+ const host = {+ isLiveEngine: () => live,+ messages: {},+ webhookService: { dispatch },+ eventsGateway: { emitPollVote },+ } as unknown as SessionEngineWiringHost;+ const cb = new SessionEngineEventWiring({ logger: createLogger('test') }).buildCallbacks(+ 'sess-1',+ {} as IWhatsAppEngine,+ 'sess-1-name',+ host,+ );+ return { cb, dispatch, emitPollVote };+ };++ it('publishes the vote with its session to the webhook and the WebSocket', () => {+ const { cb, dispatch, emitPollVote } = setup(true);++ cb.onPollVote?.(vote);++ const payload = { sessionId: 'sess-1', ...vote };+ expect(dispatch).toHaveBeenCalledWith('sess-1', 'poll.vote', payload);+ expect(emitPollVote).toHaveBeenCalledWith('sess-1', payload);+ });++ it('publishes a cleared vote too: an empty selection is news', () => {+ const { cb, dispatch } = setup(true);++ cb.onPollVote?.({ ...vote, selectedOptions: [] });++ expect(dispatch).toHaveBeenCalledWith('sess-1', 'poll.vote', expect.objectContaining({ selectedOptions: [] }));+ });++ it('publishes nothing for a vote without a poll message id', () => {+ const { cb, dispatch, emitPollVote } = setup(true);++ cb.onPollVote?.({ ...vote, pollMessageId: '' });++ expect(dispatch).not.toHaveBeenCalled();+ expect(emitPollVote).not.toHaveBeenCalled();+ });++ it('publishes nothing from an engine that is no longer live', () => {+ const { cb, dispatch, emitPollVote } = setup(false);++ cb.onPollVote?.(vote);++ expect(dispatch).not.toHaveBeenCalled();+ expect(emitPollVote).not.toHaveBeenCalled();+ });+});diff --git a/src/modules/webhook/dto/webhook.dto.ts b/src/modules/webhook/dto/webhook.dto.tsindex 8d33e3102..23e15d26b 100644--- a/src/modules/webhook/dto/webhook.dto.ts+++ b/src/modules/webhook/dto/webhook.dto.ts@@ -94,6 +94,7 @@ export const WEBHOOK_EVENTS = ['session.restriction','presence.update','event.response',+ 'poll.vote','group.join','group.leave','group.update',diff --git a/src/modules/webhook/utils/idempotency.util.spec.ts b/src/modules/webhook/utils/idempotency.util.spec.tsindex 38c187930..4615c4bc1 100644--- a/src/modules/webhook/utils/idempotency.util.spec.ts+++ b/src/modules/webhook/utils/idempotency.util.spec.ts@@ -315,6 +315,18 @@ describe('Idempotency Utils', () => {expect(generateIdempotencyKey('event.response', { ...data, sessionId: 'B' }, at)).not.toBe(key);});+ it('keys poll.vote on the session + poll + voter + vote time (distinct per change, stable across retries)', () => {+ const at = '2026-07-20T00:00:00.000Z';+ const data = { sessionId: 'A', pollMessageId: 'POLL1', voterId: 'V1', selectedOptions: ['Yes'], timestamp: 100 };+ const key = generateIdempotencyKey('poll.vote', data, at);+ expect(key).toBe('vote_A_POLL1_V1_100');+ expect(generateIdempotencyKey('poll.vote', data, '2026-07-20T01:00:00.000Z')).toBe(key);+ // Going back to an earlier selection later is a new change, never deduped against the first.+ expect(generateIdempotencyKey('poll.vote', { ...data, timestamp: 200 }, at)).not.toBe(key);+ // Two voters on the same poll in the same second are two events.+ expect(generateIdempotencyKey('poll.vote', { ...data, voterId: 'V2' }, at)).not.toBe(key);+ });+it('keys call.received on the session + call id (unique per call, no occurrence salt needed)', () => {const at = '2026-07-20T00:00:00.000Z';const data = { sessionId: 'A', callId: 'CALL1', from: '[email protected]', timestamp: 1782000000 };diff --git a/src/modules/webhook/utils/idempotency.util.ts b/src/modules/webhook/utils/idempotency.util.tsindex c9449f333..89a29408b 100644--- a/src/modules/webhook/utils/idempotency.util.ts+++ b/src/modules/webhook/utils/idempotency.util.ts@@ -118,6 +118,12 @@ export function generateIdempotencyKey(event: string, data: Record<string, unkno// id, so (session, RSVP id) is already unique per occurrence and stable across retries.return `rsvp_${toStr(data.sessionId)}_${toStr(data.responseMessageId)}`;+ case 'poll.vote':+ // A vote carries no id of its own, but each change of a voter's selection is stamped by the+ // voter's clock, so (session, poll, voter, timestamp) is distinct per change and stable across+ // retries. A voter who goes back to an earlier selection is a new change with a new timestamp.+ return `vote_${toStr(data.sessionId)}_${toStr(data.pollMessageId)}_${toStr(data.voterId)}_${toStr(data.timestamp)}`;+case 'presence.update':// Keyed on the chat and salted per occurrence. Only genuine state CHANGES are dispatched, and// a contact who types, stops, and types again produces the same payload each time — content