Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs: place event.response in the callback, scoping and filter notes
Yudhi Armyndharisf5f1d797dbb3
diff --git a/docs/03-system-architecture.md b/docs/03-system-architecture.mdindex c55c0206e..654b537cb 100644--- a/docs/03-system-architecture.md+++ b/docs/03-system-architecture.md@@ -923,6 +923,7 @@ export interface EngineEventCallbacks {onMessageRevoked?: (message: RevokedMessage) => void;onMessageReaction?: (event: ReactionEvent) => void;onMessageEdited?: (message: EditedMessage) => void;+ onEventResponse?: (event: EventResponseEvent) => void; // an RSVP to a WhatsApp event; Baileys 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; // bulk initial sync; persist, don't dispatchdiff --git a/docs/06-api-specification.md b/docs/06-api-specification.mdindex b7c620751..6e396d13b 100644--- a/docs/06-api-specification.md+++ b/docs/06-api-specification.md@@ -7148,7 +7148,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 and presence 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 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.- **`sessionId: "*"`** subscribes to every session; **`events: ["*"]`** subscribes to every subscribable event. They combine (e.g. `"*"` + `["*"]` = every 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 `"*"`.@@ -7256,7 +7256,7 @@ These are the events OpenWA actually emits. A webhook is registered with an `eve> }> ```>-> `response` is one of `going`, `not_going`, `maybe` or `unknown`. A guest who changes their answer sends a new RSVP with a new `responseMessageId`, so the event with the latest `timestamp` per `responderId` is the current answer. Order by `timestamp` rather than by arrival: delivery order is not guaranteed (see the offline note below). `extraGuestCount` is present only when WhatsApp sends it, and `eventName` only when the event's creation message can still be read from the message store. `contact` names the responder like `message.received` names its sender: `name` from the account's addressbook, `pushName` from their own profile, each present only when known, and the whole field absent when neither is. It is read from the contacts the session already holds, with no WhatsApp lookup per answer, so a responder the session knows nothing about yet arrives without one.+> `response` is one of `going`, `not_going`, `maybe` or `unknown`. A guest who changes their answer sends a new RSVP with a new `responseMessageId`, so the event with the latest `timestamp` per `responderId` is the current answer. Order by `timestamp` rather than by arrival: delivery order is not guaranteed (see the offline note below). `extraGuestCount` is present only when WhatsApp sends it, and `eventName` only when the event's creation message can still be read from the message store. `contact` names the responder like `message.received` names its sender: `name` from the account's addressbook, `pushName` from their own profile, each present only when known, and the whole field absent when neither is. It is read from the contacts the session already holds, with no WhatsApp lookup per answer, so a responder the session knows nothing about yet arrives without one. Webhook `filters` define no fields for this event, so a webhook's conditions do not narrow it: scope RSVPs to a chat by checking `chatId` on receipt.>> 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, the other person's answer to an event they posted themselves cannot be decrypted (Baileys derives the event's creator from their side of the chat) and is not reported. Answers given while the session was offline are reported when WhatsApp replays them on reconnect, but Baileys merges the replayed updates per event, so several answers to one event given while offline, even from different guests, arrive as the last one only. whatsapp-web.js accepts the subscription and never fires the event.