Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

feat(webhooks): add opt-in message.receipt event for per-recipient receipts

KGMA7427406a00c900
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8f772681e..90e2b73b6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -15,6 +15,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Add bounded webhook failure redrive with optional payload retention.
- Expose caller-supplied send idempotency keys in all five SDKs.
- Add optional 24-hour idempotency keys to twelve single-recipient send routes.
+- Add the opt-in `message.receipt` event for per-recipient group and status receipts on Baileys (#1748).
- Add opt-in archive-only chat media with dashboard previews.
diff --git a/dashboard/src/i18n/locales/ar.json b/dashboard/src/i18n/locales/ar.json
index e8dd14770..eaff3826c 100644
--- a/dashboard/src/i18n/locales/ar.json
+++ b/dashboard/src/i18n/locales/ar.json
@@ -543,6 +543,7 @@
"message.received": "عند استقبال رسالة",
"message.sent": "عند إرسال رسالة",
"message.ack": "عند تغيّر حالة تسليم رسالة أو قراءتها",
+ "message.receipt": "عند استلام كل مستلم لرسالة مجموعة أو حالة أرسلتها أو قراءتها أو تشغيلها (Baileys فقط؛ غير مضمّن في *)",
"message.failed": "عند فشل تسليم رسالة صادرة",
"message.revoked": "عند حذف رسالة لدى الجميع",
"message.reaction": "عند إضافة تفاعل أو تغييره أو إزالته",
diff --git a/dashboard/src/i18n/locales/de.json b/dashboard/src/i18n/locales/de.json
index dbc30a16f..3d84800a7 100644
--- a/dashboard/src/i18n/locales/de.json
+++ b/dashboard/src/i18n/locales/de.json
@@ -518,6 +518,7 @@
"message.received": "Wenn eine Nachricht empfangen wird",
"message.sent": "Wenn eine Nachricht gesendet wird",
"message.ack": "Wenn sich der Zustell- oder Lesestatus einer Nachricht ändert",
+ "message.receipt": "Jeder Empfänger, der eine von Ihnen gesendete Gruppen- oder Statusnachricht erhält, liest oder abspielt (nur Baileys; nicht in * enthalten)",
"message.failed": "Wenn eine ausgehende Nachricht nicht zugestellt werden kann",
"message.revoked": "Wenn eine Nachricht für alle gelöscht wird",
"message.reaction": "Wenn eine Reaktion hinzugefügt, geändert oder entfernt wird",
diff --git a/dashboard/src/i18n/locales/en.json b/dashboard/src/i18n/locales/en.json
index 511921d0e..70d84b3af 100644
--- a/dashboard/src/i18n/locales/en.json
+++ b/dashboard/src/i18n/locales/en.json
@@ -518,6 +518,7 @@
"message.received": "When a message is received",
"message.sent": "When a message is sent",
"message.ack": "When a message's delivery or read status changes",
+ "message.receipt": "Each recipient receiving, reading or playing a group or status message you sent (Baileys only; not included in *)",
"message.failed": "When an outgoing message fails to deliver",
"message.revoked": "When a message is deleted for everyone",
"message.reaction": "When a reaction is added, changed or removed",
diff --git a/dashboard/src/i18n/locales/es.json b/dashboard/src/i18n/locales/es.json
index efcb31733..a4b147c61 100644
--- a/dashboard/src/i18n/locales/es.json
+++ b/dashboard/src/i18n/locales/es.json
@@ -524,6 +524,7 @@
"message.received": "Cuando se recibe un mensaje",
"message.sent": "Cuando se envía un mensaje",
"message.ack": "Cuando cambia el estado de entrega o lectura de un mensaje",
+ "message.receipt": "Cada destinatario que recibe, lee o reproduce un mensaje de grupo o estado que enviaste (solo Baileys; no incluido en *)",
"message.failed": "Cuando falla la entrega de un mensaje saliente",
"message.revoked": "Cuando se elimina un mensaje para todos",
"message.reaction": "Cuando se añade, cambia o quita una reacción",
diff --git a/dashboard/src/i18n/locales/fr.json b/dashboard/src/i18n/locales/fr.json
index 4ee7d12e1..5e50f7bdc 100644
--- a/dashboard/src/i18n/locales/fr.json
+++ b/dashboard/src/i18n/locales/fr.json
@@ -524,6 +524,7 @@
"message.received": "Lorsqu'un message est reçu",
"message.sent": "Lorsqu'un message est envoyé",
"message.ack": "Lorsque l'état de remise ou de lecture d'un message change",
+ "message.receipt": "Chaque destinataire qui reçoit, lit ou écoute un message de groupe ou de statut que vous avez envoyé (Baileys uniquement ; non inclus dans *)",
"message.failed": "Lorsqu'un message sortant n'a pas pu être remis",
"message.revoked": "Lorsqu'un message est supprimé pour tout le monde",
"message.reaction": "Lorsqu'une réaction est ajoutée, modifiée ou retirée",
diff --git a/dashboard/src/i18n/locales/he.json b/dashboard/src/i18n/locales/he.json
index eecb53b79..ba449ec8f 100644
--- a/dashboard/src/i18n/locales/he.json
+++ b/dashboard/src/i18n/locales/he.json
@@ -531,6 +531,7 @@
"message.received": "כאשר מתקבלת הודעה",
"message.sent": "כאשר נשלחת הודעה",
"message.ack": "כאשר סטטוס המסירה או הקריאה של הודעה משתנה",
+ "message.receipt": "כל נמען שמקבל, קורא או מנגן הודעת קבוצה או סטטוס ששלחת (Baileys בלבד; לא כלול ב-*)",
"message.failed": "כאשר מסירת הודעה יוצאת נכשלת",
"message.revoked": "כאשר הודעה נמחקת אצל כולם",
"message.reaction": "כאשר תגובה נוספת, משתנה או מוסרת",
diff --git a/dashboard/src/i18n/locales/hi.json b/dashboard/src/i18n/locales/hi.json
index 575869917..4a39efa4b 100644
--- a/dashboard/src/i18n/locales/hi.json
+++ b/dashboard/src/i18n/locales/hi.json
@@ -518,6 +518,7 @@
"message.received": "जब कोई संदेश प्राप्त होता है",
"message.sent": "जब कोई संदेश भेजा जाता है",
"message.ack": "जब किसी संदेश की डिलीवरी या पढ़ने की स्थिति बदलती है",
+ "message.receipt": "आपके भेजे गए समूह या स्टेटस संदेश को हर प्राप्तकर्ता द्वारा प्राप्त करने, पढ़ने या चलाने पर (केवल Baileys; * में शामिल नहीं)",
"message.failed": "जब कोई आउटगोइंग संदेश डिलीवर होने में विफल रहता है",
"message.revoked": "जब कोई संदेश सभी के लिए हटा दिया जाता है",
"message.reaction": "जब कोई प्रतिक्रिया जोड़ी जाती है, बदली जाती है या हटाई जाती है",
diff --git a/dashboard/src/i18n/locales/id.json b/dashboard/src/i18n/locales/id.json
index cced742f9..bba30c7a6 100644
--- a/dashboard/src/i18n/locales/id.json
+++ b/dashboard/src/i18n/locales/id.json
@@ -518,6 +518,7 @@
"message.received": "Saat pesan diterima",
"message.sent": "Saat pesan dikirim",
"message.ack": "Saat status pengiriman atau status baca pesan berubah",
+ "message.receipt": "Setiap penerima yang menerima, membaca, atau memutar pesan grup atau status yang Anda kirim (hanya Baileys; tidak termasuk dalam *)",
"message.failed": "Saat pesan keluar gagal terkirim",
"message.revoked": "Saat pesan dihapus untuk semua orang",
"message.reaction": "Saat reaksi ditambahkan, diubah atau dihapus",
diff --git a/dashboard/src/i18n/locales/it.json b/dashboard/src/i18n/locales/it.json
index 679173aac..67753b322 100644
--- a/dashboard/src/i18n/locales/it.json
+++ b/dashboard/src/i18n/locales/it.json
@@ -524,6 +524,7 @@
"message.received": "Quando viene ricevuto un messaggio",
"message.sent": "Quando viene inviato un messaggio",
"message.ack": "Quando cambia lo stato di consegna o di lettura di un messaggio",
+ "message.receipt": "Ogni destinatario che riceve, legge o riproduce un messaggio di gruppo o di stato che hai inviato (solo Baileys; non incluso in *)",
"message.failed": "Quando la consegna di un messaggio in uscita non riesce",
"message.revoked": "Quando un messaggio viene eliminato per tutti",
"message.reaction": "Quando una reazione viene aggiunta, modificata o rimossa",
diff --git a/dashboard/src/i18n/locales/ko.json b/dashboard/src/i18n/locales/ko.json
index 479961fb1..2ca2ee4f6 100644
--- a/dashboard/src/i18n/locales/ko.json
+++ b/dashboard/src/i18n/locales/ko.json
@@ -518,6 +518,7 @@
"message.received": "메시지를 받았을 때",
"message.sent": "메시지를 보냈을 때",
"message.ack": "메시지의 전달 또는 읽음 상태가 바뀌었을 때",
+ "message.receipt": "보낸 그룹 또는 상태 메시지를 각 수신자가 받거나 읽거나 재생했을 때 (Baileys 전용, *에 포함되지 않음)",
"message.failed": "보낸 메시지의 전달이 실패했을 때",
"message.revoked": "메시지가 모두에게서 삭제되었을 때",
"message.reaction": "반응이 추가, 변경 또는 삭제되었을 때",
diff --git a/dashboard/src/i18n/locales/pt-BR.json b/dashboard/src/i18n/locales/pt-BR.json
index 155a70407..189aa7335 100644
--- a/dashboard/src/i18n/locales/pt-BR.json
+++ b/dashboard/src/i18n/locales/pt-BR.json
@@ -524,6 +524,7 @@
"message.received": "Quando uma mensagem é recebida",
"message.sent": "Quando uma mensagem é enviada",
"message.ack": "Quando o status de entrega ou leitura de uma mensagem muda",
+ "message.receipt": "Cada destinatário que recebe, lê ou reproduz uma mensagem de grupo ou status que você enviou (somente Baileys; não incluído em *)",
"message.failed": "Quando a entrega de uma mensagem enviada falha",
"message.revoked": "Quando uma mensagem é apagada para todos",
"message.reaction": "Quando uma reação é adicionada, alterada ou removida",
diff --git a/dashboard/src/i18n/locales/te.json b/dashboard/src/i18n/locales/te.json
index 34823975f..a507e01dd 100644
--- a/dashboard/src/i18n/locales/te.json
+++ b/dashboard/src/i18n/locales/te.json
@@ -518,6 +518,7 @@
"message.received": "సందేశం వచ్చినప్పుడు",
"message.sent": "సందేశం పంపబడినప్పుడు",
"message.ack": "సందేశం డెలివరీ లేదా చదివిన స్థితి మారినప్పుడు",
+ "message.receipt": "మీరు పంపిన గ్రూప్ లేదా స్టేటస్ సందేశాన్ని ప్రతి గ్రహీత అందుకున్నప్పుడు, చదివినప్పుడు లేదా ప్లే చేసినప్పుడు (Baileys మాత్రమే; *లో చేర్చబడదు)",
"message.failed": "పంపిన సందేశం డెలివరీ విఫలమైనప్పుడు",
"message.revoked": "సందేశం అందరికీ తొలగించబడినప్పుడు",
"message.reaction": "ప్రతిస్పందన జోడించబడినప్పుడు, మార్చబడినప్పుడు లేదా తీసివేయబడినప్పుడు",
diff --git a/dashboard/src/i18n/locales/tr.json b/dashboard/src/i18n/locales/tr.json
index 1f8043cd1..c0396a350 100644
--- a/dashboard/src/i18n/locales/tr.json
+++ b/dashboard/src/i18n/locales/tr.json
@@ -518,6 +518,7 @@
"message.received": "Bir mesaj alındığında",
"message.sent": "Bir mesaj gönderildiğinde",
"message.ack": "Bir mesajın teslim veya okunma durumu değiştiğinde",
+ "message.receipt": "Gönderdiğiniz bir grup veya durum mesajını her alıcının alması, okuması ya da oynatması (yalnızca Baileys; * kapsamında değil)",
"message.failed": "Giden bir mesaj teslim edilemediğinde",
"message.revoked": "Bir mesaj herkesten silindiğinde",
"message.reaction": "Bir tepki eklendiğinde, değiştirildiğinde veya kaldırıldığında",
diff --git a/dashboard/src/i18n/locales/zh-CN.json b/dashboard/src/i18n/locales/zh-CN.json
index 4cd71ee55..c43ec1a46 100644
--- a/dashboard/src/i18n/locales/zh-CN.json
+++ b/dashboard/src/i18n/locales/zh-CN.json
@@ -518,6 +518,7 @@
"message.received": "收到消息时",
"message.sent": "发送消息时",
"message.ack": "消息的送达或已读状态变化时",
+ "message.receipt": "你发送的群组或状态消息被每位接收者送达、阅读或播放时(仅 Baileys;不包含在 * 中)",
"message.failed": "发出的消息投递失败时",
"message.revoked": "消息被撤回时",
"message.reaction": "添加、更改或移除回应时",
diff --git a/dashboard/src/i18n/locales/zh-HK.json b/dashboard/src/i18n/locales/zh-HK.json
index 96e3412a9..ce64b4c24 100644
--- a/dashboard/src/i18n/locales/zh-HK.json
+++ b/dashboard/src/i18n/locales/zh-HK.json
@@ -518,6 +518,7 @@
"message.received": "收到訊息時",
"message.sent": "傳送訊息時",
"message.ack": "訊息的送達或已讀狀態變更時",
+ "message.receipt": "你傳送的群組或狀態訊息被每位接收者送達、閱讀或播放時(僅限 Baileys;不包含在 * 中)",
"message.failed": "發出的訊息傳送失敗時",
"message.revoked": "訊息被收回時",
"message.reaction": "新增、變更或移除回應時",
diff --git a/dashboard/src/utils/webhookEvents.ts b/dashboard/src/utils/webhookEvents.ts
index 405d7e088..c1aa1eff6 100644
--- a/dashboard/src/utils/webhookEvents.ts
+++ b/dashboard/src/utils/webhookEvents.ts
@@ -6,6 +6,7 @@ export const availableEventNames = [
'message.received',
'message.sent',
'message.ack',
+ 'message.receipt',
'message.failed',
'message.revoked',
'message.reaction',
diff --git a/docs/03-system-architecture.md b/docs/03-system-architecture.md
index 11683c2b1..45290ec50 100644
--- a/docs/03-system-architecture.md
+++ b/docs/03-system-architecture.md
@@ -920,6 +920,7 @@ export interface EngineEventCallbacks {
onMessage?: (message: IncomingMessage) => void;
onMessageCreate?: (message: IncomingMessage) => void; // outgoing (incl. linked-phone sends)
onMessageAck?: (messageId: string, status: DeliveryStatus) => void;
+ onMessageReceipt?: (event: MessageReceiptEvent) => void; // per-recipient group/status receipts (Baileys only)
onMessageRevoked?: (message: RevokedMessage) => void;
onMessageReaction?: (event: ReactionEvent) => void;
onMessageEdited?: (message: EditedMessage) => void;
diff --git a/docs/05-database-design.md b/docs/05-database-design.md
index 1d631930e..940153e39 100644
--- a/docs/05-database-design.md
+++ b/docs/05-database-design.md
@@ -464,6 +464,7 @@ CREATE TABLE webhooks (
"message.received",
"message.sent",
"message.ack",
+ "message.receipt",
"message.failed",
"message.revoked",
"message.reaction",
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index ff5d4eb17..28e7c4869 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -4591,7 +4591,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` 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`, `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. Five 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) 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 also 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.
#### GET /api/sessions/:sessionId/webhooks
@@ -7107,12 +7107,13 @@ Error `code` values include `UNAUTHORIZED`, `INVALID_MESSAGE`, `INVALID_SESSION`
### Subscribable events
-`events` accepts the wildcard `"*"` (all of the below) or any of these exact names:
+`events` accepts the wildcard `"*"` (all of the below except `message.receipt`, which must be named explicitly) or any of these exact names:
```
message.received
message.sent
message.ack
+message.receipt
message.revoked
message.reaction
message.edited
@@ -7139,7 +7140,7 @@ A subscribe request whose `events` array contains no recognized name (after filt
### Wildcards and scoping
-- **`sessionId: "*"`** subscribes to every session; **`events: ["*"]`** subscribes to every subscribable event. They combine (e.g. `"*"` + `["*"]` = every event of every session).
+- **`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 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 `"*"`.
- **Live sockets are re-validated against the database once a minute**, with no client activity required. A socket carries the key as it stood when it connected, and rooms joined earlier are never revisited, so that snapshot is what the sweep compares against the current row, along with any later `subscribe` whose key no longer matched it (what that `subscribe` granted outlives the change, so putting the row back does not spare the socket). It closes the key's sockets with an `UNAUTHORIZED` frame naming the cause: `API key has been deleted`, `API key has been revoked`, `API key has expired`, or `API key authorization changed; please reconnect` when `role`, `allowedIps`, `allowedSessions`, `allowedChats` or `expiresAt` moved. A change made through this API still evicts synchronously in the same request; the sweep is what catches an expiry, a change written straight to this node's main database, or one committed in the instant a socket was connecting. API keys are per node (see [13 - Horizontal Scaling](./13-horizontal-scaling.md)), so a change made on another node never reaches this node's sockets; repeat it on every node. A rename, and the usage counters the gateway itself writes, evict nobody. Treat these frames as "reconnect and resubscribe", not as fatal.
@@ -7191,13 +7192,14 @@ Every registered webhook receives an HTTP `POST` with a JSON body of this shape:
### Event catalog
-These are the events OpenWA actually emits. A webhook is registered with an `events` list; an event is delivered to a webhook when its `events` array includes the event name or `"*"`.
+These are the events OpenWA actually emits. A webhook is registered with an `events` list; an event is delivered to a webhook when its `events` array includes the event name or `"*"` (`"*"` excludes `message.receipt`, which is delivered only when named).
| Event | When it fires | `data` payload sketch |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `message.received` | An inbound message arrives | The full message object: `id`, `from`, `to`, `body`, `type`, `timestamp` (epoch **seconds**), `isGroup`, `kind` (user-facing chat discriminator of `chatId` — `individual\|group\|channel\|status\|broadcast\|unknown`), `fromMe`, `chatId`, `media{mimetype,filename?,data?,omitted?,sizeBytes?}` (media messages only), `contact{…}` (plus optional `senderPhone` for `@lid` senders, `order{orderId,token?}` / `product{productId,…}` on `order` / `product` messages, `buttons:[{id,text}]` on a WhatsApp Business prompt that offers choices, and `button{id,text?}` when the sender tapped one; **Baileys only**) |
| `message.sent` | An outbound message is created/sent from this session | Same message object shape as `message.received` |
| `message.ack` | A delivery/read receipt updates an outbound message | `{ id, messageId, status, ack }` — `status` is the canonical state (`pending`/`sent`/`delivered`/`read`/`failed`); `ack` is the deprecated legacy integer derived from it |
+| `message.receipt` | One recipient receives, reads or plays a group or status message the account sent (**Baileys only**; not included in `*`) | `{ id, messageId, chatId, participant, status, timestamp }` — one event per recipient and status; `status` is `delivered`/`read`/`played`, `timestamp` is epoch **seconds**. Receipts from the account's own linked devices are not reported. On Baileys 7.0.0-rc14 a played voice note reports `read`. Nothing is stored and `message.ack` is not advanced by it |
| `message.failed` | A receipt resolves to `failed` (dispatched in addition to `message.ack`) | `{ id, messageId, status: "failed", ack: -1 }` |
| `message.revoked` | A message is deleted/recalled | `{ id, revokedId?, chatId, from, to, type: "revoked", body: "", timestamp }` — **reconcile on `revokedId`** (the original deleted message's id), falling back to `id`. On whatsapp-web.js `id` is the _revocation notification_ (a distinct message that won't match a stored id) and `revokedId` may be absent when the original isn't cached locally; on Baileys the two coincide |
| `message.reaction` | A reaction is added, changed, or removed | `{ messageId, chatId, reaction, senderId, reactions? }` — `reactions` is the post-apply `{ senderId: emoji }` snapshot, omitted when the gateway holds no stored copy of the message to compute it from (an ephemeral message, or one predating the session going live); treat it as unknown rather than empty and keep the map you already hold. `reaction` is empty when removed |
@@ -7289,6 +7291,7 @@ Every delivery includes:
- `message.received` / `message.sent`: `msg_{sessionId}_{messageId}`
- `message.ack`: `ack_{sessionId}_{messageId}_{status}`
+- `message.receipt`: `receipt_{sessionId}_{messageId}_{participant}_{status}`
- `message.failed`: `failed_{sessionId}_{messageId}_{status}`
- `message.revoked`: `rev_{sessionId}_{messageId}`
- `message.edited`: `edit_{sessionId}_{messageId}_{occurredAt}`
diff --git a/docs/12-troubleshooting-faq.md b/docs/12-troubleshooting-faq.md
index aa205847c..ca64d2fdd 100644
--- a/docs/12-troubleshooting-faq.md
+++ b/docs/12-troubleshooting-faq.md
@@ -1416,6 +1416,7 @@ available_events:
- message.received # New incoming message
- message.sent # Message sent
- message.ack # Message status update (sent, delivered, read)
+ - message.receipt # One recipient received/read/played a group or status message you sent (Baileys only; not included in "*", must be listed explicitly)
- message.failed # Receipt resolved to failed
- message.revoked # Message deleted
- message.reaction # Reaction added, changed, or removed
diff --git a/docs/21-glossary.md b/docs/21-glossary.md
index d6ecfaaa4..19c122021 100644
--- a/docs/21-glossary.md
+++ b/docs/21-glossary.md
@@ -91,6 +91,7 @@ A system-emitted occurrence, for example:
- `message.received`: New incoming message
- `message.ack`: Message status changed
+- `message.receipt`: One recipient received, read or played a group or status message the account sent
- `session.status`: Session status changed
- `session.qr`: New QR code generated
diff --git a/docs/22-n8n-integration.md b/docs/22-n8n-integration.md
index 224ac35b7..6a124f56f 100644
--- a/docs/22-n8n-integration.md
+++ b/docs/22-n8n-integration.md
@@ -78,6 +78,7 @@ Start workflows when WhatsApp events occur.
| `message.received` | New incoming message | Auto-reply, lead capture |
| `message.sent` | Message sent successfully | Delivery confirmation |
| `message.ack` | Delivery/read status advanced | Read receipts |
+| `message.receipt` | Per-recipient group/status receipt (Baileys) | Per-member read tracking |
| `message.failed` | Outgoing message failed | Failure alerting |
| `message.revoked` | Message deleted for everyone | Deletion tracking |
| `message.reaction` | Reaction added / changed / removed | Reaction tracking |
diff --git a/docs/29-engine-capability-matrix.md b/docs/29-engine-capability-matrix.md
index ee43e58e8..a114f54da 100644
--- a/docs/29-engine-capability-matrix.md
+++ b/docs/29-engine-capability-matrix.md
@@ -814,7 +814,7 @@ OpenWA consumes events by normalizing them into `EngineEventCallbacks`; anything
| --------------------------- | --------------------------------------------------- | --- | -------------------------------- | ------------------------------- |
| `messages.upsert` | ✅ | | `chats.lock` | ❌ |
| `messages.update` | ✅ | | `message-capping.update` | ❌ |
-| `messages.reaction` | ❌ — inbound reactions arrive via `messages.upsert` | | `message-receipt.update` | ❌ |
+| `messages.reaction` | ❌ — inbound reactions arrive via `messages.upsert` | | `message-receipt.update` | ✅ |
| `messages.delete` | ❌ candidate (delete-for-me webhook) | | `messages.media-update` | ❌ |
| `messaging-history.set` | ✅ | | `messaging-history.status` | ❌ |
| `chats.upsert` | ✅ | | `newsletter-participants.update` | ❌ |
@@ -1025,7 +1025,7 @@ adapter sources — re-derive the same way when anything changes:
4 internal wiring, 1 class plumbing, **35 ❌ not exposed** (27 real capabilities + 8
session/transport settings that are not WhatsApp capabilities). The backlog is the ❌ rows minus
those 8 settings; 🔩 plumbing is correctly never exposed.
-- Events: Baileys **34** (17 consumed / 17 dropped), wwjs **31** (16 consumed / 15 dropped).
+- Events: Baileys **34** (18 consumed / 16 dropped), wwjs **31** (16 consumed / 15 dropped).
- **0** capabilities in 29.5.3: every capability with first-class symbols on both libraries is
either wired or classified with evidence. Some are Baileys-only despite typed whatsapp-web.js
symbols: `createGroup`, whose injected evaluate reaches a page internal without `findImpl`;
diff --git a/openapi.json b/openapi.json
index ee6355986..967d79759 100644
--- a/openapi.json
+++ b/openapi.json
@@ -19229,7 +19229,7 @@
},
"events": {
"type": "array",
- "description": "Event types to subscribe to. '*' subscribes to all events.",
+ "description": "Event types to subscribe to. '*' subscribes to all events except `message.receipt`, which must be named explicitly.",
"example": [
"message.received",
"session.status"
@@ -19241,6 +19241,7 @@
"message.received",
"message.sent",
"message.ack",
+ "message.receipt",
"message.failed",
"message.revoked",
"message.reaction",
@@ -19337,6 +19338,7 @@
"message.received",
"message.sent",
"message.ack",
+ "message.receipt",
"message.failed",
"message.revoked",
"message.reaction",
@@ -19428,7 +19430,7 @@
},
"events": {
"type": "array",
- "description": "Event types to subscribe to. '*' subscribes to all events.",
+ "description": "Event types to subscribe to. '*' subscribes to all events except `message.receipt`, which must be named explicitly.",
"minItems": 1,
"items": {
"type": "string",
@@ -19436,6 +19438,7 @@
"message.received",
"message.sent",
"message.ack",
+ "message.receipt",
"message.failed",
"message.revoked",
"message.reaction",
diff --git a/sdk/go/client_test.go b/sdk/go/client_test.go
index 9e2fb4726..9fd405ed9 100644
--- a/sdk/go/client_test.go
+++ b/sdk/go/client_test.go
@@ -1180,6 +1180,7 @@ func TestWebhookEventWireValues(t *testing.T) {
EventMessageReceived: "message.received",
EventMessageSent: "message.sent",
EventMessageAck: "message.ack",
+ EventMessageReceipt: "message.receipt",
EventMessageFailed: "message.failed",
EventMessageRevoked: "message.revoked",
EventMessageReaction: "message.reaction",
diff --git a/sdk/go/types_webhook.go b/sdk/go/types_webhook.go
index 39f813bd1..72bc5521f 100644
--- a/sdk/go/types_webhook.go
+++ b/sdk/go/types_webhook.go
@@ -14,6 +14,7 @@ const (
EventMessageReceived WebhookEvent = "message.received"
EventMessageSent WebhookEvent = "message.sent"
EventMessageAck WebhookEvent = "message.ack"
+ EventMessageReceipt WebhookEvent = "message.receipt"
EventMessageFailed WebhookEvent = "message.failed"
EventMessageRevoked WebhookEvent = "message.revoked"
EventMessageReaction WebhookEvent = "message.reaction"
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.java
index 3ad8ddc18..3edc03197 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
@@ -14,6 +14,8 @@ public enum WebhookEvent {
MESSAGE_SENT,
@SerializedName("message.ack")
MESSAGE_ACK,
+ @SerializedName("message.receipt")
+ MESSAGE_RECEIPT,
@SerializedName("message.failed")
MESSAGE_FAILED,
@SerializedName("message.revoked")
diff --git a/sdk/javascript/src/types.ts b/sdk/javascript/src/types.ts
index a7416ddf2..64148ddf7 100644
--- a/sdk/javascript/src/types.ts
+++ b/sdk/javascript/src/types.ts
@@ -926,11 +926,12 @@ export interface SetProfilePictureRequest {
// ── Webhook ───────────────────────────────────────────────────────
-/** Events a webhook may subscribe to. Use `*` to receive all. */
+/** Events a webhook may subscribe to. Use `*` to receive all except `message.receipt`, which must be named. */
export type WebhookEvent =
| 'message.received'
| 'message.sent'
| 'message.ack'
+ | 'message.receipt'
| 'message.failed'
| 'message.revoked'
| 'message.reaction'
diff --git a/sdk/python/openwa/types.py b/sdk/python/openwa/types.py
index d5b016c5d..4dd87e2be 100644
--- a/sdk/python/openwa/types.py
+++ b/sdk/python/openwa/types.py
@@ -65,7 +65,7 @@ MessageType = Literal[
"unknown",
]
WebhookEvent = Literal[
- "message.received", "message.sent", "message.ack", "message.failed", "message.revoked",
+ "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",
"group.join", "group.leave", "group.update", "group.join_request",
@@ -75,7 +75,7 @@ WebhookEvent = Literal[
]
# The events a delivery can carry: WebhookEvent without the "*" subscription wildcard.
WebhookDeliveryEvent = Literal[
- "message.received", "message.sent", "message.ack", "message.failed", "message.revoked",
+ "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",
"group.join", "group.leave", "group.update", "group.join_request",
diff --git a/src/common/utils/wildcard-events.ts b/src/common/utils/wildcard-events.ts
new file mode 100644
index 000000000..b7b450518
--- /dev/null
+++ b/src/common/utils/wildcard-events.ts
@@ -0,0 +1,11 @@
+/**
+ * Events a '*' subscription (webhook or socket) does NOT receive; they are delivered only when named
+ * explicitly. A `message.receipt` fires once per recipient (a message to a 1,000-member group yields
+ * about 2,000), so folding it into '*' would multiply the traffic of every existing catch-all subscriber.
+ */
+export const WILDCARD_EXCLUDED_EVENTS: readonly string[] = ['message.receipt'];
+
+/** Whether a subscription to `events` covers `event`, honouring the '*' exclusions above. */
+export function subscriptionCoversEvent(events: readonly string[], event: string): boolean {
+ return events.includes(event) || (events.includes('*') && !WILDCARD_EXCLUDED_EVENTS.includes(event));
+}
diff --git a/src/engine/adapters/baileys-events.spec.ts b/src/engine/adapters/baileys-events.spec.ts
index da9588c5f..c1a4bc96f 100644
--- a/src/engine/adapters/baileys-events.spec.ts
+++ b/src/engine/adapters/baileys-events.spec.ts
@@ -3,6 +3,7 @@ import { createLogger } from '../../common/services/logger.service';
import { ConcurrencyLimiter } from '../../common/utils/concurrency-limiter';
import { inboundMediaConcurrency } from './inbound-media-cap';
import type { WAMessage, WASocket } from '@whiskeysockets/baileys';
+import type { MessageReceiptEvent } from '../interfaces/whatsapp-engine.interface';
/**
* `downloadMediaMessage` is a jest mock, not a silent no-op: the real-download branch
@@ -117,6 +118,7 @@ function makeHost(overrides: Partial<BaileysEventsHost> = {}): BaileysEventsHost
getOnMessageEdited: () => undefined,
getOnMessageReaction: () => undefined,
getOnMessageAck: () => undefined,
+ getOnMessageReceipt: () => undefined,
getOnGroupEvent: () => undefined,
getOnCall: () => undefined,
getOnPresenceUpdate: () => undefined,
@@ -630,3 +632,81 @@ describe('BaileysEvents record of messages deleted for everyone', () => {
expect(events.wasDeletedForEveryone(`M${limit}`)).toBe(true);
});
});
+
+describe('BaileysEvents.handleMessageReceiptUpdate', () => {
+ const group = '[email protected]';
+ const member = '[email protected]';
+
+ function setup(overrides: Partial<BaileysEventsHost> = {}) {
+ const onMessageReceipt = jest.fn();
+ const events = new BaileysEvents(makeHost({ getOnMessageReceipt: () => onMessageReceipt, ...overrides }));
+ return { events, onMessageReceipt };
+ }
+
+ it('reports one event per recipient receipt of a message the account sent', () => {
+ const { events, onMessageReceipt } = setup();
+ events.handleMessageReceiptUpdate([
+ {
+ key: { id: 'OUT1', remoteJid: group, fromMe: true },
+ receipt: { userJid: member, receiptTimestamp: 1700000000 },
+ },
+ { key: { id: 'OUT1', remoteJid: group, fromMe: true }, receipt: { userJid: member, readTimestamp: 1700000060 } },
+ ]);
+ expect(onMessageReceipt.mock.calls).toEqual([
+ [{ messageId: 'OUT1', chatId: group, participant: member, status: 'delivered', timestamp: 1700000000 }],
+ [{ messageId: 'OUT1', chatId: group, participant: member, status: 'read', timestamp: 1700000060 }],
+ ]);
+ });
+
+ it('splits a buffered entry that carries several timestamps into one event per status', () => {
+ const { events, onMessageReceipt } = setup();
+ events.handleMessageReceiptUpdate([
+ {
+ key: { id: 'OUT1', remoteJid: group, fromMe: true },
+ receipt: { userJid: member, receiptTimestamp: 1, readTimestamp: 2, playedTimestamp: 3 },
+ },
+ ]);
+ const calls = onMessageReceipt.mock.calls as Array<[MessageReceiptEvent]>;
+ expect(calls.map(([e]) => [e.status, e.timestamp])).toEqual([
+ ['delivered', 1],
+ ['read', 2],
+ ['played', 3],
+ ]);
+ });
+
+ it("drops receipts from the account's own devices, in either dialect", () => {
+ const { events, onMessageReceipt } = setup({
+ getSocketOrNull: () =>
+ ({ user: { id: '6280000000000:[email protected]', lid: '99999@lid' } }) as unknown as WASocket,
+ });
+ events.handleMessageReceiptUpdate([
+ {
+ key: { id: 'OUT1', remoteJid: group, fromMe: true },
+ receipt: { userJid: '[email protected]', readTimestamp: 1 },
+ },
+ { key: { id: 'OUT1', remoteJid: group, fromMe: true }, receipt: { userJid: '99999@lid', readTimestamp: 1 } },
+ ]);
+ expect(onMessageReceipt).not.toHaveBeenCalled();
+ });
+
+ it('ignores receipts for messages the account did not send, and malformed entries', () => {
+ const { events, onMessageReceipt } = setup();
+ events.handleMessageReceiptUpdate([
+ { key: { id: 'IN1', remoteJid: group, fromMe: false }, receipt: { userJid: member, readTimestamp: 1 } },
+ { key: { remoteJid: group, fromMe: true }, receipt: { userJid: member, readTimestamp: 1 } },
+ { key: { id: 'OUT1', remoteJid: group, fromMe: true }, receipt: { readTimestamp: 1 } },
+ { key: { id: 'OUT1', remoteJid: group, fromMe: true }, receipt: { userJid: member } },
+ ]);
+ expect(onMessageReceipt).not.toHaveBeenCalled();
+ });
+
+ it('neutralises the chat and participant ids', () => {
+ const { events, onMessageReceipt } = setup({ toNeutralJid: (jid: string) => `n:${jid}` });
+ events.handleMessageReceiptUpdate([
+ { key: { id: 'OUT1', remoteJid: group, fromMe: true }, receipt: { userJid: '55555@lid', readTimestamp: 1 } },
+ ]);
+ expect(onMessageReceipt).toHaveBeenCalledWith(
+ expect.objectContaining({ chatId: `n:${group}`, participant: 'n:55555@lid' }),
+ );
+ });
+});
diff --git a/src/engine/adapters/baileys-events.ts b/src/engine/adapters/baileys-events.ts
index dc15b0175..9d4763c06 100644
--- a/src/engine/adapters/baileys-events.ts
+++ b/src/engine/adapters/baileys-events.ts
@@ -9,6 +9,8 @@ import {
PresenceState,
CallOutcome,
IncomingMessage,
+ MessageReceiptEvent,
+ MessageReceiptStatus,
MessageType,
ReactionEvent,
RevokedMessage,
@@ -201,6 +203,8 @@ export interface BaileysEventsHost {
getOnMessageReaction(): EngineEventCallbacks['onMessageReaction'];
/** The currently-registered onMessageAck callback, if any (assigned at initialize()). */
getOnMessageAck(): EngineEventCallbacks['onMessageAck'];
+ /** The currently-registered onMessageReceipt callback, if any (assigned at initialize()). */
+ getOnMessageReceipt(): EngineEventCallbacks['onMessageReceipt'];
/** The currently-registered onGroupEvent callback, if any (assigned at initialize()). */
getOnGroupEvent(): EngineEventCallbacks['onGroupEvent'];
/** The currently-registered onCall callback, if any (assigned at initialize()). */
@@ -778,6 +782,78 @@ export class BaileysEvents {
}
}
+ /**
+ * Baileys `message-receipt.update`: per-participant receipts, which Baileys raises only for group
+ * and status messages (1:1 receipts arrive as `messages.update` instead). Only receipts for
+ * messages this account sent are reported, and receipts from the account's own linked devices are
+ * dropped. The event buffer can merge several receipts of one participant into one entry, so each
+ * timestamp the entry carries becomes its own event. rc14 files a `played` receipt under
+ * `readTimestamp`, so on that version a voice note that was played reports `read`.
+ */
+ handleMessageReceiptUpdate(
+ updates: Array<{
+ key?: { id?: string | null; remoteJid?: string | null; fromMe?: boolean | null };
+ receipt?: {
+ userJid?: string | null;
+ receiptTimestamp?: number | { toNumber(): number } | null;
+ readTimestamp?: number | { toNumber(): number } | null;
+ playedTimestamp?: number | { toNumber(): number } | null;
+ };
+ }>,
+ ): void {
+ const onReceipt = this.host.getOnMessageReceipt();
+ if (!onReceipt) {
+ return;
+ }
+ const isSelf = this.selfMatcher();
+ for (const { key, receipt } of Array.isArray(updates) ? updates : []) {
+ if (!key?.id || !key.remoteJid || key.fromMe !== true || !receipt?.userJid || isSelf(receipt.userJid)) {
+ continue;
+ }
+ const stamps: Array<[MessageReceiptStatus, typeof receipt.receiptTimestamp]> = [
+ ['delivered', receipt.receiptTimestamp],
+ ['read', receipt.readTimestamp],
+ ['played', receipt.playedTimestamp],
+ ];
+ for (const [status, ts] of stamps) {
+ if (ts == null) continue;
+ const event: MessageReceiptEvent = {
+ messageId: key.id,
+ chatId: this.host.toNeutralJid(key.remoteJid),
+ participant: this.host.toNeutralJid(receipt.userJid),
+ status,
+ timestamp: toUnixSeconds(ts),
+ };
+ onReceipt(event);
+ }
+ }
+ }
+
+ /**
+ * Matches any jid of this account, in either dialect and from any of its devices (user parts are
+ * compared). Answers false for everything while the account's own id is unknown.
+ */
+ private selfMatcher(): (jid: string | null | undefined) => boolean {
+ const selfJid = this.host.normalizedSelfJid();
+ if (!selfJid) {
+ return () => false;
+ }
+ const phone = userPart(selfJid);
+ const lid = this.host.getSocketOrNull()?.user?.lid;
+ const lidUser = lid ? userPart(lid) : undefined;
+ return (jid: string | null | undefined): boolean => {
+ if (!jid) return false;
+ const { kind, userPart: user } = parseWaId(jid);
+ if (kind === 'user') return user === phone;
+ if (kind !== 'lid') return false;
+ if (lidUser !== undefined) return user === lidUser;
+ // Creds carrying no `user.lid` leave nothing to compare a lid-addressed jid against, and every
+ // such comparison would answer false. Fall back to the session's own lid to phone mapping,
+ // which the store learns from the same traffic.
+ return userPart(this.host.toNeutralJid(jid)) === phone;
+ };
+ }
+
/**
* Baileys `group-participants.update`: a membership change. Only add/remove map to the neutral
* join/leave kinds — promote/demote (and 'modify', a phone-number-change rewrite) change no
@@ -828,21 +904,9 @@ export class BaileysEvents {
if (!selfJid) {
return; // no own id to report as the joining participant
}
- const phone = userPart(selfJid);
- const lid = this.host.getSocketOrNull()?.user?.lid;
- const lidUser = lid ? userPart(lid) : undefined;
- const isSelf = (jid: string | undefined): boolean => {
- if (!jid) return false;
- const { kind, userPart: user } = parseWaId(jid);
- if (kind === 'user') return user === phone;
- if (kind !== 'lid') return false;
- if (lidUser !== undefined) return user === lidUser;
- // Creds carrying no `user.lid` leave nothing to compare a lid-addressed actor against, and
- // every such comparison would answer false: a group this session created would then be
- // reported as a join of itself. Fall back to the session's own lid to phone mapping, which the
- // store learns from the same traffic.
- return userPart(this.host.toNeutralJid(jid)) === phone;
- };
+ // Without the lid fallback inside selfMatcher, a group this session created by a lid-addressed
+ // actor would be reported as a join of itself.
+ const isSelf = this.selfMatcher();
for (const group of Array.isArray(groups) ? groups : []) {
// Live, whatsapp-web.js emits no group.join when the session created the group, so that entry is
// skipped. The acting participant alone does not identify it: an invite-link join may name the
diff --git a/src/engine/adapters/baileys-inbound-burst.spec.ts b/src/engine/adapters/baileys-inbound-burst.spec.ts
index 0b14df378..bc768b3f1 100644
--- a/src/engine/adapters/baileys-inbound-burst.spec.ts
+++ b/src/engine/adapters/baileys-inbound-burst.spec.ts
@@ -61,6 +61,7 @@ describe('BaileysEvents inbound media burst', () => {
getOnMessageEdited: () => undefined,
getOnMessageReaction: () => undefined,
getOnMessageAck: () => undefined,
+ getOnMessageReceipt: () => undefined,
getOnGroupEvent: () => undefined,
getOnCall: () => undefined,
getOnPresenceUpdate: () => undefined,
diff --git a/src/engine/adapters/baileys-lifecycle.ts b/src/engine/adapters/baileys-lifecycle.ts
index 096154d41..a5a6a5f92 100644
--- a/src/engine/adapters/baileys-lifecycle.ts
+++ b/src/engine/adapters/baileys-lifecycle.ts
@@ -147,6 +147,7 @@ export interface BaileysLifecycleHost {
addLidMappings: BaileysSessionStore['addLidMappings'];
handleMessagesUpsert: BaileysEvents['handleMessagesUpsert'];
handleMessagesUpdate: BaileysEvents['handleMessagesUpdate'];
+ handleMessageReceiptUpdate: BaileysEvents['handleMessageReceiptUpdate'];
logContactEvent: BaileysEvents['logContactEvent'];
handleGroupParticipantsUpdate: BaileysEvents['handleGroupParticipantsUpdate'];
handleGroupsUpdate: BaileysEvents['handleGroupsUpdate'];
@@ -325,7 +326,7 @@ export class BaileysLifecycle {
}
// An internal reconnect (transient drop) overwrites this.sock WITHOUT going through
- // disconnect/logout/destroy, so the previous socket's WebSocket and the 17 ev listeners we
+ // disconnect/logout/destroy, so the previous socket's WebSocket and the 18 ev listeners we
// register below would leak on every reconnect. Tear the prior socket down first. Detach OUR
// connection.update listener BEFORE end(): Baileys' own end() synchronously emits a synthetic
// connection.update {connection:'close'}, which — if still wired — would re-enter
@@ -337,6 +338,7 @@ export class BaileysLifecycle {
previous.ev.removeAllListeners('creds.update');
previous.ev.removeAllListeners('messages.upsert');
previous.ev.removeAllListeners('messages.update');
+ previous.ev.removeAllListeners('message-receipt.update');
previous.ev.removeAllListeners('contacts.upsert');
previous.ev.removeAllListeners('contacts.update');
previous.ev.removeAllListeners('chats.upsert');
@@ -456,6 +458,7 @@ export class BaileysLifecycle {
sock.ev.on('connection.update', update => this.handleConnectionUpdate(update));
sock.ev.on('messages.upsert', event => this.host.handleMessagesUpsert(event));
sock.ev.on('messages.update', updates => this.host.handleMessagesUpdate(updates));
+ sock.ev.on('message-receipt.update', updates => this.host.handleMessageReceiptUpdate(updates));
sock.ev.on('contacts.upsert', contacts => {
this.host.logContactEvent('contacts.upsert', contacts);
this.host.upsertContacts(contacts);
diff --git a/src/engine/adapters/baileys-media-abort.spec.ts b/src/engine/adapters/baileys-media-abort.spec.ts
index f4fad5254..4a24c9007 100644
--- a/src/engine/adapters/baileys-media-abort.spec.ts
+++ b/src/engine/adapters/baileys-media-abort.spec.ts
@@ -52,6 +52,7 @@ function build(dispatcher?: object): { events: BaileysEvents; warns: string[] }
getOnMessageEdited: () => undefined,
getOnMessageReaction: () => undefined,
getOnMessageAck: () => undefined,
+ getOnMessageReceipt: () => undefined,
getOnGroupEvent: () => undefined,
getOnCall: () => undefined,
getOnPresenceUpdate: () => undefined,
diff --git a/src/engine/adapters/baileys.adapter.spec.ts b/src/engine/adapters/baileys.adapter.spec.ts
index 16a2fda89..a8572ffd5 100644
--- a/src/engine/adapters/baileys.adapter.spec.ts
+++ b/src/engine/adapters/baileys.adapter.spec.ts
@@ -2764,6 +2764,25 @@ describe('BaileysAdapter inbound fan-out', () => {
expect(onMessageAck).toHaveBeenCalledWith('OUT1', 'delivered');
});
+ it('emits onMessageReceipt from message-receipt.update for a group message the account sent', async () => {
+ const onMessageReceipt = jest.fn();
+ const adapter = newAdapter();
+ await adapter.initialize({ onMessageReceipt });
+ fakeSock.fire('message-receipt.update', [
+ {
+ key: { id: 'OUT1', remoteJid: '[email protected]', fromMe: true },
+ receipt: { userJid: '[email protected]', readTimestamp: 1700000000 },
+ },
+ ]);
+ expect(onMessageReceipt).toHaveBeenCalledWith({
+ messageId: 'OUT1',
+ chatId: '[email protected]',
+ participant: '[email protected]',
+ status: 'read',
+ timestamp: 1700000000,
+ });
+ });
+
it('inbound image: downloads media and exposes base64 + caption as body', async () => {
// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
const baileys = jest.requireMock('@whiskeysockets/baileys') as {
diff --git a/src/engine/adapters/baileys.adapter.ts b/src/engine/adapters/baileys.adapter.ts
index 38edbc8b1..06071b9a8 100644
--- a/src/engine/adapters/baileys.adapter.ts
+++ b/src/engine/adapters/baileys.adapter.ts
@@ -157,6 +157,7 @@ export class BaileysAdapter implements IWhatsAppEngine {
getOnMessageEdited: () => this.callbacks.onMessageEdited,
getOnMessageReaction: () => this.callbacks.onMessageReaction,
getOnMessageAck: () => this.callbacks.onMessageAck,
+ getOnMessageReceipt: () => this.callbacks.onMessageReceipt,
getOnGroupEvent: () => this.callbacks.onGroupEvent,
getOnCall: () => this.callbacks.onCall,
getOnPresenceUpdate: () => this.callbacks.onPresenceUpdate,
@@ -197,6 +198,7 @@ export class BaileysAdapter implements IWhatsAppEngine {
addLidMappings: mappings => this.sessionStore.addLidMappings(mappings),
handleMessagesUpsert: event => this.events.handleMessagesUpsert(event),
handleMessagesUpdate: updates => this.events.handleMessagesUpdate(updates),
+ handleMessageReceiptUpdate: updates => this.events.handleMessageReceiptUpdate(updates),
logContactEvent: (event, records) => this.events.logContactEvent(event, records),
handleGroupParticipantsUpdate: event => this.events.handleGroupParticipantsUpdate(event),
handleGroupsUpdate: updates => this.events.handleGroupsUpdate(updates),
diff --git a/src/engine/interfaces/whatsapp-engine.interface.ts b/src/engine/interfaces/whatsapp-engine.interface.ts
index c0d31e92b..fd2e89f86 100644
--- a/src/engine/interfaces/whatsapp-engine.interface.ts
+++ b/src/engine/interfaces/whatsapp-engine.interface.ts
@@ -796,6 +796,25 @@ export interface CallOutcomeEvent {
timestamp: number;
}
+/** What one recipient did with an outgoing message. `played` applies to voice notes and view-once media. */
+export type MessageReceiptStatus = 'delivered' | 'read' | 'played';
+
+/**
+ * One recipient's receipt for a message the account sent (group and status messages, where WhatsApp
+ * reports each participant separately). Receipts from the account's own linked devices are dropped
+ * by the adapter, so `participant` is always someone else.
+ */
+export interface MessageReceiptEvent {
+ messageId: string;
+ /** Neutral id of the chat the message was sent to (the group, or `status@broadcast`). */
+ chatId: string;
+ /** Neutral id of the recipient the receipt came from. */
+ participant: string;
+ status: MessageReceiptStatus;
+ /** Unix seconds the recipient reached this status (engine timestamp). */
+ timestamp: number;
+}
+
export interface EngineEventCallbacks {
onQRCode?: (qr: string) => void;
onReady?: (phone: string, pushName: string) => void;
@@ -810,6 +829,11 @@ export interface EngineEventCallbacks {
* delivery signal to the neutral `DeliveryStatus`, so consumers never see engine-specific codes.
*/
onMessageAck?: (messageId: string, status: DeliveryStatus) => void;
+ /**
+ * Fired once per recipient as each one receives, reads or plays a message the account sent to a
+ * group or status. Baileys only: whatsapp-web.js has no per-participant receipt event.
+ */
+ onMessageReceipt?: (event: MessageReceiptEvent) => void;
onMessageRevoked?: (message: RevokedMessage) => void;
onMessageReaction?: (event: ReactionEvent) => void;
onMessageEdited?: (message: EditedMessage) => void;
diff --git a/src/modules/events/dto/ws-messages.dto.ts b/src/modules/events/dto/ws-messages.dto.ts
index cbe142251..b30bbbcfb 100644
--- a/src/modules/events/dto/ws-messages.dto.ts
+++ b/src/modules/events/dto/ws-messages.dto.ts
@@ -10,6 +10,7 @@ export const SUBSCRIBABLE_EVENTS = [
'message.received',
'message.sent',
'message.ack',
+ 'message.receipt',
'message.revoked',
'message.reaction',
'message.edited',
diff --git a/src/modules/events/events.gateway.spec.ts b/src/modules/events/events.gateway.spec.ts
index f7bbe2f82..668fb18a2 100644
--- a/src/modules/events/events.gateway.spec.ts
+++ b/src/modules/events/events.gateway.spec.ts
@@ -827,6 +827,32 @@ describe('EventsGateway session.qr role gate', () => {
expect(sock.rooms.has(QR_DENIED_ROOM)).toBe(true);
expect(qrEvents(sock)).toEqual([]);
});
+
+ it('delivers message.receipt only to sockets that named it, never through a wildcard', async () => {
+ const wildcard = await connect('operator');
+ await subscribe(wildcard, '*', ['*']);
+ const sessionWildcard = await connect('operator');
+ await subscribe(sessionWildcard, 'sess-1', ['*']);
+ const named = await connect('operator');
+ await subscribe(named, 'sess-1', ['message.receipt']);
+ const namedAllSessions = await connect('operator');
+ await subscribe(namedAllSessions, '*', ['message.receipt']);
+
+ gateway.emitMessageReceipt('sess-1', {
+ id: 'OUT1',
+ messageId: 'OUT1',
+ chatId: '[email protected]',
+ participant: '[email protected]',
+ status: 'read',
+ timestamp: 1700000000,
+ });
+
+ const events = (s: RoomSocket): string[] => s.received.map(m => m.payload.event);
+ expect(events(wildcard)).toEqual([]);
+ expect(events(sessionWildcard)).toEqual([]);
+ expect(events(named)).toEqual(['message.receipt']);
+ expect(events(namedAllSessions)).toEqual(['message.receipt']);
+ });
});
describe('event catalog ⇔ emitter invariants (drift guard)', () => {
diff --git a/src/modules/events/events.gateway.ts b/src/modules/events/events.gateway.ts
index 49c52cbfb..1f862f1e8 100644
--- a/src/modules/events/events.gateway.ts
+++ b/src/modules/events/events.gateway.ts
@@ -59,7 +59,8 @@ import type {
WSPongResponse,
} from './dto/ws-messages.dto';
import { SUBSCRIBABLE_EVENTS, buildRoomName } from './dto/ws-messages.dto';
-import type { DeliveryStatus } from '../../engine/interfaces/whatsapp-engine.interface';
+import type { DeliveryStatus, MessageReceiptStatus } from '../../engine/interfaces/whatsapp-engine.interface';
+import { WILDCARD_EXCLUDED_EVENTS } from '../../common/utils/wildcard-events';
/**
* Whether an API key may subscribe to a session's WebSocket event rooms.
@@ -757,11 +758,12 @@ export class EventsGateway implements OnGatewayInit, OnGatewayConnection, OnGate
// them receives the event exactly once (Socket.IO dedups recipients per
// broadcast). Four separate .emit() calls would deliver one copy per room.
// `except` is resolved by the adapter, so the exclusion also holds across nodes with Redis.
- const broadcast = this.server
- .to(buildRoomName(sessionId, event))
- .to(buildRoomName(sessionId, '*'))
- .to(buildRoomName('*', event))
- .to(buildRoomName('*', '*'));
+ // An event in WILDCARD_EXCLUDED_EVENTS skips the two event-'*' rooms: only sockets that named it
+ // (for one session or for all) receive it.
+ const named = this.server.to(buildRoomName(sessionId, event)).to(buildRoomName('*', event));
+ const broadcast = WILDCARD_EXCLUDED_EVENTS.includes(event)
+ ? named
+ : named.to(buildRoomName(sessionId, '*')).to(buildRoomName('*', '*'));
(exceptRoom ? broadcast.except(exceptRoom) : broadcast).emit('message', eventMessage);
}
@@ -870,6 +872,24 @@ export class EventsGateway implements OnGatewayInit, OnGatewayConnection, OnGate
this.emitToRooms(sessionId, 'message.ack', data);
}
+ /**
+ * Emit one recipient's receipt for a group or status message the account sent. Mirrors the
+ * `message.receipt` webhook. Not delivered to '*' subscriptions (see WILDCARD_EXCLUDED_EVENTS).
+ */
+ emitMessageReceipt(
+ sessionId: string,
+ data: {
+ id: string;
+ messageId: string;
+ chatId: string;
+ participant: string;
+ status: MessageReceiptStatus;
+ timestamp: number;
+ },
+ ) {
+ this.emitToRooms(sessionId, 'message.receipt', data);
+ }
+
/**
* Emit message revoked ("deleted for everyone") notification
*/
diff --git a/src/modules/session/message-projector.service.ts b/src/modules/session/message-projector.service.ts
index 6cba5820b..c3f7dcae1 100644
--- a/src/modules/session/message-projector.service.ts
+++ b/src/modules/session/message-projector.service.ts
@@ -22,6 +22,7 @@ import type { StatusUpdate } from '../status-store/entities/status-update.entity
import {
IWhatsAppEngine,
DeliveryStatus,
+ MessageReceiptEvent,
IncomingMessage,
ReactionEvent,
EditedMessage,
@@ -851,6 +852,26 @@ export class MessageProjector {
);
}
+ /**
+ * Engine callback body for one recipient's receipt (Baileys group and status messages). Nothing is
+ * stored: the event is forwarded as is, over the socket and the webhook with the same shape. `id`
+ * mirrors the other message.* events (and is what the idempotency-key resolver reads); `chatId` lets
+ * webhook chatId filters scope it.
+ */
+ handleMessageReceipt(id: string, engine: IWhatsAppEngine, event: MessageReceiptEvent): void {
+ if (!this.engines.isLive(id, engine)) return;
+ const payload = {
+ id: event.messageId,
+ messageId: event.messageId,
+ chatId: event.chatId,
+ participant: event.participant,
+ status: event.status,
+ timestamp: event.timestamp,
+ };
+ this.eventsGateway.emitMessageReceipt(id, payload);
+ void this.webhookService.dispatch(id, 'message.receipt', payload);
+ }
+
/**
* Advance a stored message's delivery status, returning the rows changed. Scoped by sessionId:
* waMessageId is unique per account/chat, not global, so an ack on one session must never advance a
diff --git a/src/modules/session/session-engine-event-wiring.ts b/src/modules/session/session-engine-event-wiring.ts
index 0788ac580..b52ab85ed 100644
--- a/src/modules/session/session-engine-event-wiring.ts
+++ b/src/modules/session/session-engine-event-wiring.ts
@@ -243,6 +243,7 @@ export class SessionEngineEventWiring {
},
onMessageCreate: (message): void => host.messages.handleOwnSendEcho(id, engine, message),
onMessageAck: (messageId, status): void => host.messages.handleMessageAck(id, engine, messageId, status),
+ onMessageReceipt: (event): void => host.messages.handleMessageReceipt(id, engine, event),
onMessageRevoked: (message): void => host.messages.handleMessageRevoked(id, engine, message),
onMessageReaction: (event): void => {
if (!host.isLiveEngine(id, engine)) return;
diff --git a/src/modules/session/session.service.spec.ts b/src/modules/session/session.service.spec.ts
index f45eedcd7..5b00c0e26 100644
--- a/src/modules/session/session.service.spec.ts
+++ b/src/modules/session/session.service.spec.ts
@@ -208,6 +208,7 @@ describe('SessionService', () => {
emitMessage: jest.fn(),
emitMessageSent: jest.fn(),
emitMessageAck: jest.fn(),
+ emitMessageReceipt: jest.fn(),
emitMessageRevoked: jest.fn(),
emitMessageReaction: jest.fn(),
emitMessageEdited: jest.fn(),
@@ -5763,6 +5764,35 @@ describe('SessionService', () => {
expect(socketPayload.ack).toBeDefined();
});
+ it('forwards a per-recipient receipt as message.receipt, identically over the socket and the webhook', async () => {
+ const callbacks = await startAndCaptureCallbacks();
+ expect(typeof callbacks.onMessageReceipt).toBe('function');
+
+ callbacks.onMessageReceipt!({
+ messageId: 'wa-out-1',
+ chatId: '[email protected]',
+ participant: '[email protected]',
+ status: 'read',
+ timestamp: 1700000000,
+ });
+ await flush();
+
+ const receiptCalls = (eventsGateway.emitMessageReceipt as jest.Mock).mock.calls as unknown[][];
+ const socketPayload = receiptCalls[0][1] as Record<string, unknown>;
+ const webhookPayload = dispatchedEvents('message.receipt')[0][2] as Record<string, unknown>;
+ expect(socketPayload).toEqual(webhookPayload);
+ expect(socketPayload).toEqual({
+ id: 'wa-out-1',
+ messageId: 'wa-out-1',
+ chatId: '[email protected]',
+ participant: '[email protected]',
+ status: 'read',
+ timestamp: 1700000000,
+ });
+ // A receipt is not the message's own tick: it never advances the stored status or fires message.ack.
+ expect(dispatchedEvents('message.ack')).toHaveLength(0);
+ });
+
it("reflects delivery on the stored message: 'delivered' updates status to DELIVERED (#220)", async () => {
const callbacks = await startAndCaptureCallbacks();
diff --git a/src/modules/webhook/dto/webhook.dto.ts b/src/modules/webhook/dto/webhook.dto.ts
index bb717c92b..9e8955546 100644
--- a/src/modules/webhook/dto/webhook.dto.ts
+++ b/src/modules/webhook/dto/webhook.dto.ts
@@ -80,6 +80,7 @@ export const WEBHOOK_EVENTS = [
'message.received',
'message.sent',
'message.ack',
+ 'message.receipt',
'message.failed',
'message.revoked',
'message.reaction',
@@ -121,7 +122,8 @@ export class CreateWebhookDto {
url!: string;
@ApiPropertyOptional({
- description: "Event types to subscribe to. '*' subscribes to all events.",
+ description:
+ "Event types to subscribe to. '*' subscribes to all events except `message.receipt`, which must be named explicitly.",
example: ['message.received', 'session.status'],
enum: [...WEBHOOK_EVENTS, '*'],
type: String,
@@ -209,7 +211,8 @@ export class UpdateWebhookDto {
url?: string;
@ApiPropertyOptional({
- description: "Event types to subscribe to. '*' subscribes to all events.",
+ description:
+ "Event types to subscribe to. '*' subscribes to all events except `message.receipt`, which must be named explicitly.",
enum: [...WEBHOOK_EVENTS, '*'],
type: String,
isArray: true,
diff --git a/src/modules/webhook/utils/deliver-once.spec.ts b/src/modules/webhook/utils/deliver-once.spec.ts
index a3d253383..c63efa757 100644
--- a/src/modules/webhook/utils/deliver-once.spec.ts
+++ b/src/modules/webhook/utils/deliver-once.spec.ts
@@ -110,6 +110,12 @@ describe('isDeliverableWebhook', () => {
expect(isDeliverableWebhook({ active: true, events: ['*'] }, 'message.ack')).toBe(true);
});
+ it('keeps message.receipt out of a wildcard subscription but delivers it when named', () => {
+ expect(isDeliverableWebhook({ active: true, events: ['*'] }, 'message.receipt')).toBe(false);
+ expect(isDeliverableWebhook({ active: true, events: ['*', 'message.receipt'] }, 'message.receipt')).toBe(true);
+ expect(isDeliverableWebhook({ active: true, events: ['message.receipt'] }, 'message.receipt')).toBe(true);
+ });
+
it('refuses a missing, disabled or unsubscribed row', () => {
expect(isDeliverableWebhook(null, 'message.received')).toBe(false);
expect(isDeliverableWebhook(undefined, 'message.received')).toBe(false);
diff --git a/src/modules/webhook/utils/deliver-once.ts b/src/modules/webhook/utils/deliver-once.ts
index 008636f0b..601fa843a 100644
--- a/src/modules/webhook/utils/deliver-once.ts
+++ b/src/modules/webhook/utils/deliver-once.ts
@@ -4,6 +4,7 @@ import { withSafeFetch, redactSsrfError, isSsrfProtectionEnabled } from '../../.
import { type LoggerService } from '../../../common/services/logger.service';
import { WebhookDeliveryFailure } from '../entities/webhook-delivery-failure.entity';
import { recordWebhookDeliveryFailure, statusCodeFromError } from './record-delivery-failure';
+import { subscriptionCoversEvent } from '../../../common/utils/wildcard-events';
/**
* Drop operator-supplied custom headers that target the names the system sets (Content-Type,
@@ -28,7 +29,7 @@ export function sanitizeCustomHeaders(custom: Record<string, string> | null | un
/**
* Whether a webhook row as read now may still receive `event`: it exists, is active and subscribes to
- * the event or to '*' (an events column that is not an array subscribes to nothing). Its filters are
+ * the event or to '*' (minus WILDCARD_EXCLUDED_EVENTS; an events column that is not an array subscribes to nothing). Its filters are
* not re-applied here, since they need the event data. Every path that delivers after the dispatch
* moment (a queued job, a direct retry, an outbox replay) runs this against a fresh row, so a removed,
* disabled or unsubscribed webhook stops receiving the event.
@@ -37,7 +38,7 @@ export function isDeliverableWebhook<T extends { active: boolean; events: string
row: T | null | undefined,
event: string,
): row is T {
- return !!row && row.active && Array.isArray(row.events) && (row.events.includes(event) || row.events.includes('*'));
+ return !!row && row.active && Array.isArray(row.events) && subscriptionCoversEvent(row.events, event);
}
/** HMAC-SHA256 over the exact pre-serialized body, prefixed for receiver-side verification. */
diff --git a/src/modules/webhook/utils/idempotency.util.spec.ts b/src/modules/webhook/utils/idempotency.util.spec.ts
index e3533c9fe..fa0ded5df 100644
--- a/src/modules/webhook/utils/idempotency.util.spec.ts
+++ b/src/modules/webhook/utils/idempotency.util.spec.ts
@@ -7,6 +7,21 @@ describe('Idempotency Utils', () => {
expect(key).toBe('msg_A_ABC123');
});
+ it('keys message.receipt by recipient and status, so two members reading the same message stay distinct', () => {
+ const read = (participant: string): string =>
+ generateIdempotencyKey('message.receipt', { id: 'ABC123', participant, status: 'read', sessionId: 'A' });
+ expect(read('[email protected]')).toBe('[email protected]_read');
+ expect(read('[email protected]')).not.toBe(read('[email protected]'));
+ expect(
+ generateIdempotencyKey('message.receipt', {
+ id: 'ABC123',
+ participant: '[email protected]',
+ status: 'delivered',
+ sessionId: 'A',
+ }),
+ ).not.toBe(read('[email protected]'));
+ });
+
it('falls back to the legacy `ack` integer for message.ack when no `status` is present', () => {
const key = generateIdempotencyKey('message.ack', { messageId: 'ABC123', ack: 3, sessionId: 'A' });
expect(key).toBe('ack_A_ABC123_3');
diff --git a/src/modules/webhook/utils/idempotency.util.ts b/src/modules/webhook/utils/idempotency.util.ts
index 82c3e4ddf..506747a10 100644
--- a/src/modules/webhook/utils/idempotency.util.ts
+++ b/src/modules/webhook/utils/idempotency.util.ts
@@ -50,6 +50,10 @@ export function generateIdempotencyKey(event: string, data: Record<string, unkno
// the legacy `ack` integer for backward compatibility with older payloads.
return `ack_${toStr(data.sessionId)}_${toStr(data.id ?? data.messageId)}_${toStr(data.status ?? data.ack, '0')}`;
+ case 'message.receipt':
+ // One receipt per recipient and status: the participant keeps two members' `read` apart.
+ return `receipt_${toStr(data.sessionId)}_${toStr(data.id ?? data.messageId)}_${toStr(data.participant)}_${toStr(data.status)}`;
+
case 'message.failed':
return `failed_${toStr(data.sessionId)}_${toStr(data.id ?? data.messageId)}_${toStr(data.status ?? data.ack, '0')}`;
diff --git a/src/modules/webhook/webhook-delivery.service.spec.ts b/src/modules/webhook/webhook-delivery.service.spec.ts
index 9d8496869..c39f2aab3 100644
--- a/src/modules/webhook/webhook-delivery.service.spec.ts
+++ b/src/modules/webhook/webhook-delivery.service.spec.ts
@@ -1016,6 +1016,15 @@ describe('WebhookDeliveryService', () => {
expect(mockFetch).toHaveBeenCalled();
});
+ it('should NOT dispatch message.receipt to a wildcard (*) webhook, which must name it', async () => {
+ const webhook = createMockWebhook({ events: ['*'] });
+ (repository.find as jest.Mock).mockResolvedValue([webhook]);
+
+ await service.dispatch('sess-1', 'message.receipt', { id: 'OUT1', participant: '[email protected]', status: 'read' });
+
+ expect(mockFetch).not.toHaveBeenCalled();
+ });
+
it('should skip dispatch when plugin cancels via hook', async () => {
const webhook = createMockWebhook({ events: ['message.received'] });
(repository.find as jest.Mock).mockResolvedValue([webhook]);
diff --git a/src/modules/webhook/webhook-delivery.service.ts b/src/modules/webhook/webhook-delivery.service.ts
index c61ddb80f..e8e2649ce 100644
--- a/src/modules/webhook/webhook-delivery.service.ts
+++ b/src/modules/webhook/webhook-delivery.service.ts
@@ -26,6 +26,7 @@ import { redactSsrfError } from '../../common/security/ssrf-guard';
import { HookManager } from '../../core/hooks';
import { ConcurrencyLimiter } from '../../common/utils/concurrency-limiter';
import { isWebhookBeforeResult } from '../../core/hooks/hook-results';
+import { subscriptionCoversEvent } from '../../common/utils/wildcard-events';
export interface WebhookPayload {
event: string;
@@ -298,9 +299,7 @@ export class WebhookDeliveryService implements OnModuleInit, OnModuleDestroy {
// other webhook of the session. A `filters` that is not a plain object, or a non-array `conditions`,
// is refused explicitly: evaluateFilters reads either as "no filter", which would deliver every
// subscribed event unfiltered.
- const subscribed = webhooks.filter(
- w => Array.isArray(w.events) && (w.events.includes(event) || w.events.includes('*')),
- );
+ const subscribed = webhooks.filter(w => Array.isArray(w.events) && subscriptionCoversEvent(w.events, event));
const matching = subscribed.filter(w => {
try {
const filters: unknown = w.filters;