Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

Merge main into feat/poll-vote-webhook

Yudhi Armyndharis247ab9a86477
diff --cc docs/06-api-specification.md
index c5b3e5885,72ba44f30..0cdd2e524
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@@ -7419,25 -7407,24 +7425,25 @@@ Every delivery includes
- `message.receipt`: `receipt_{sessionId}_{messageId}_{participant}_{status}`
- `message.failed`: `failed_{sessionId}_{messageId}_{status}`
- `message.revoked`: `rev_{sessionId}_{messageId}`
- - `message.edited`: `edit_{sessionId}_{messageId}_{occurredAt}`
- - `message.reaction`: `react_{sessionId}_{messageId}_{senderId}_{occurredAt}`
+ - `message.edited`: `edit_{sessionId}_{messageId}_{occurrenceId}`
+ - `message.reaction`: `react_{sessionId}_{messageId}_{senderId}_{occurrenceId}`
- `session.qr`: `qr_{sessionId}_{hash(qr)}`
- - `session.status`: `sess_{sessionId}_{status}_{occurredAt}`
- - `session.authenticated`: `auth_{sessionId}_{hash(data)}_{occurredAt}`
- - `session.disconnected`: `disc_{sessionId}_{hash(reason)}_{occurredAt}`
- - `session.reconnect_loop`: `loop_{sessionId}_{attempts}_{occurredAt}`
- - `group.join` / `group.leave`: `grp_{groupId}_{hash(participantIds)}_{join|leave}_{occurredAt}`
- - `group.update`: `grp_{groupId}_update_{hash(changes)}_{occurredAt}`
- - `group.join_request`: `grp_{groupId}_{hash(participantIds)}_join_request_{occurredAt}` (salted like `group.join` — a rejected user can legitimately ask again)
- - `call.received`: `call_{sessionId}_{callId}` (a call id is unique per call, so no `occurredAt` salt)
- - `call.accepted` / `call.rejected` / `call.missed`: `call_{sessionId}_{callId}_{outcome}` (each call ends once, so no `occurredAt` salt)
- - `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)
+ - `session.status`: `sess_{sessionId}_{status}_{occurrenceId}`
+ - `session.authenticated`: `auth_{sessionId}_{hash(data)}_{occurrenceId}`
+ - `session.disconnected`: `disc_{sessionId}_{hash(reason)}_{occurrenceId}`
+ - `session.reconnect_loop`: `loop_{sessionId}_{attempts}_{occurrenceId}`
+ - `group.join` / `group.leave`: `grp_{groupId}_{hash(participantIds)}_{join|leave}_{occurrenceId}`
+ - `group.update`: `grp_{groupId}_update_{hash(changes)}_{occurrenceId}`
+ - `group.join_request`: `grp_{groupId}_{hash(participantIds)}_join_request_{occurrenceId}` (salted like `group.join` — a rejected user can legitimately ask again)
+ - `call.received`: `call_{sessionId}_{callId}` (a call id is unique per call, so no `occurrenceId` salt)
+ - `call.accepted` / `call.rejected` / `call.missed`: `call_{sessionId}_{callId}_{outcome}` (each call ends once, so no `occurrenceId` salt)
+ - `session.restriction`: `restr_{sessionId}_{kind}_{active}_{occurrenceId}`
+ - `presence.update`: `pres_{sessionId}_{chatId}_{hash(participants)}_{occurrenceId}`
+ - `event.response`: `rsvp_{sessionId}_{responseMessageId}` (every answer is its own message with its own id, so no `occurrenceId` salt)
++- `poll.vote`: `vote_{sessionId}_{pollMessageId}_{voterId}_{timestamp}_{hash(selectedOptions)}` (each change of a selection carries the voter's own timestamp and the selection is hashed in, so two changes within one second stay distinct and no `occurrenceId` salt is needed)
- 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.
+ 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 `occurrenceId`, a random id minted **once per dispatch and reused across that dispatch's retries**; it is not a timestamp, so two occurrences within the same millisecond still get distinct keys. 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.
### Retries with exponential backoff