Skip to content

GOWA - WhatsApp REST API with support for UI, Multi Account, Webhooks, and MCP, and Chatwoot. Built with Golang for efficient memory use.

fix(webhook): forward read receipts from the account's own linked devices (#864)

Alejandro3971c4cbdfec
diff --git a/docs/webhook-payload.md b/docs/webhook-payload.md
index a5d4e07d..b1c4deab 100644
--- a/docs/webhook-payload.md
+++ b/docs/webhook-payload.md
@@ -442,6 +442,12 @@ Triggered when a message is read by the recipient (they opened the chat and saw
}
```
+Receipts are forwarded from each user's primary device only, so a contact with several linked devices does not produce
+duplicate events. Read receipts generated by the current account itself (`"read"`, or `"read-self"` when read receipts
+are disabled in privacy settings) are forwarded from any of its devices, so opening a chat on WhatsApp Web, Desktop or
+another linked device is reported just like opening it on the phone. For these, `payload.from` is the account's own JID
+(without the device suffix) and `payload.ids` are the IDs of the incoming messages that were read.
+
### Receipt Event Fields
| **Field** | **Type** | **Description** |
diff --git a/src/infrastructure/whatsapp/AGENTS.md b/src/infrastructure/whatsapp/AGENTS.md
index 0eaf6be4..623c4cfe 100644
--- a/src/infrastructure/whatsapp/AGENTS.md
+++ b/src/infrastructure/whatsapp/AGENTS.md
@@ -14,7 +14,8 @@ This package owns clients, device lifecycle, JIDs, events, presence, and forward
- Webhooks: `event_message.go` and `webhook_forward.go`; use
[the payload contract](../../../docs/webhook-payload.md) for payload changes.
Keep work bounded and failures observable without blocking the event loop.
- Preserve the `evt.Sender.Device != 0` receipt guard to prevent linked-device duplicates.
+ Preserve the `shouldForwardReceipt` guard: contacts' linked-device receipts stay
+ dropped to prevent duplicates; only the account's own read receipts pass from any device.
- Chatwoot retries: `StartChatwootForwardRetryWorker` uses durable chat-storage jobs
keyed by device, event name, and WhatsApp message ID. Initialize the client registry
before the retry worker; preserve device routing when replaying queued events.
diff --git a/src/infrastructure/whatsapp/event_receipt.go b/src/infrastructure/whatsapp/event_receipt.go
index 6f68a7e6..e6a96920 100644
--- a/src/infrastructure/whatsapp/event_receipt.go
+++ b/src/infrastructure/whatsapp/event_receipt.go
@@ -80,21 +80,33 @@ func createReceiptPayload(ctx context.Context, evt *events.Receipt, deviceID str
// forwardReceiptToWebhook forwards message acknowledgement events to the configured webhook URLs.
//
-// IMPORTANT: We only forward receipts from the primary device (Device == 0).
-// WhatsApp sends separate receipt events for each linked device (phone, web, desktop, etc.)
-// of a user. For example, if a user has 3 devices, you would receive 3 "delivered" receipts
-// for the same message. To avoid duplicate webhooks and simplify downstream processing,
-// we only send the receipt from the primary device (Device == 0).
-//
-// If you need receipts from all devices in the future, remove the Device == 0 check below.
+// Receipts are filtered by shouldForwardReceipt; see that function for the
+// per-device rules.
func forwardReceiptToWebhook(ctx context.Context, evt *events.Receipt, deviceID string, client *whatsmeow.Client) error {
- // Only forward receipts from the primary device to avoid duplicates.
- // See function comment above for detailed explanation.
- if evt.Sender.Device != 0 {
- logrus.Debugf("Skipping receipt webhook for linked device %d (only primary device receipts are forwarded)", evt.Sender.Device)
+ if !shouldForwardReceipt(evt) {
+ logrus.Debugf("Skipping %s receipt webhook from linked device %d of %s", evt.Type, evt.Sender.Device, evt.Sender.ToNonAD())
return nil
}
payload := createReceiptPayload(ctx, evt, deviceID, client)
return forwardPayloadToConfiguredWebhooks(ctx, payload, "message.ack")
}
+
+// shouldForwardReceipt reports whether a receipt event should be forwarded.
+//
+// WhatsApp sends separate receipt events for each linked device (phone, web,
+// desktop, etc.) of a contact. For example, if a contact has 3 devices, you
+// would receive 3 "delivered" receipts for the same message. To avoid duplicate
+// webhooks we only forward the receipt from the primary device (Device == 0).
+//
+// The exception is a read receipt sent by one of the current account's own
+// devices (IsFromMe). It means the account owner read the chat on that device
+// (WhatsApp Web, Desktop or another companion), and only the device where the
+// chat was opened sends it, so it is not duplicated per device. Dropping it
+// would hide reads that did not happen on the phone.
+func shouldForwardReceipt(evt *events.Receipt) bool {
+ if evt.Sender.Device == 0 {
+ return true
+ }
+ return evt.IsFromMe && (evt.Type == types.ReceiptTypeRead || evt.Type == types.ReceiptTypeReadSelf)
+}
diff --git a/src/infrastructure/whatsapp/event_receipt_test.go b/src/infrastructure/whatsapp/event_receipt_test.go
new file mode 100644
index 00000000..5ec0e367
--- /dev/null
+++ b/src/infrastructure/whatsapp/event_receipt_test.go
@@ -0,0 +1,87 @@
+package whatsapp
+
+import (
+ "context"
+ "testing"
+ "time"
+
+ "github.com/stretchr/testify/assert"
+ "go.mau.fi/whatsmeow"
+ "go.mau.fi/whatsmeow/store"
+ "go.mau.fi/whatsmeow/types"
+ "go.mau.fi/whatsmeow/types/events"
+)
+
+func TestShouldForwardReceipt(t *testing.T) {
+ contact := types.NewJID("628123456789", types.DefaultUserServer)
+ own := types.NewJID("628111111111", types.DefaultUserServer)
+ ownLID := types.NewJID("251556368777322", types.HiddenUserServer)
+
+ withDevice := func(jid types.JID, device uint16) types.JID {
+ jid.Device = device
+ return jid
+ }
+ receipt := func(sender types.JID, fromMe bool, receiptType types.ReceiptType) *events.Receipt {
+ return &events.Receipt{
+ MessageSource: types.MessageSource{
+ Chat: contact,
+ Sender: sender,
+ IsFromMe: fromMe,
+ },
+ MessageIDs: []types.MessageID{"3EB00106E8BE0F407E88EC"},
+ Type: receiptType,
+ }
+ }
+
+ tests := []struct {
+ name string
+ evt *events.Receipt
+ want bool
+ }{
+ {"contact primary delivered", receipt(contact, false, types.ReceiptTypeDelivered), true},
+ {"contact primary read", receipt(contact, false, types.ReceiptTypeRead), true},
+ {"contact linked device delivered", receipt(withDevice(contact, 3), false, types.ReceiptTypeDelivered), false},
+ {"contact linked device read", receipt(withDevice(contact, 3), false, types.ReceiptTypeRead), false},
+ {"own primary read-self", receipt(own, true, types.ReceiptTypeReadSelf), true},
+ {"own linked device read", receipt(withDevice(own, 12), true, types.ReceiptTypeRead), true},
+ {"own linked device read-self", receipt(withDevice(own, 12), true, types.ReceiptTypeReadSelf), true},
+ {"own linked device read-self via LID", receipt(withDevice(ownLID, 12), true, types.ReceiptTypeReadSelf), true},
+ {"own linked device delivered", receipt(withDevice(own, 12), true, types.ReceiptTypeDelivered), false},
+ {"own linked device played-self", receipt(withDevice(own, 12), true, types.ReceiptTypePlayedSelf), false},
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ assert.Equal(t, tt.want, shouldForwardReceipt(tt.evt))
+ })
+ }
+}
+
+func TestCreateReceiptPayloadOwnLinkedDeviceReadSelf(t *testing.T) {
+ own := types.NewJID("628111111111", types.DefaultUserServer)
+ ownCompanion := own
+ ownCompanion.Device = 12
+ contact := types.NewJID("628123456789", types.DefaultUserServer)
+ client := &whatsmeow.Client{Store: &store.Device{ID: &own}}
+
+ body := createReceiptPayload(context.Background(), &events.Receipt{
+ MessageSource: types.MessageSource{
+ Chat: contact,
+ Sender: ownCompanion,
+ IsFromMe: true,
+ },
+ MessageIDs: []types.MessageID{"3A1", "3A2"},
+ Timestamp: time.Date(2026, time.October, 3, 10, 0, 0, 0, time.UTC),
+ Type: types.ReceiptTypeReadSelf,
+ }, own.String(), client)
+
+ assert.Equal(t, "message.ack", body["event"])
+ payload, ok := body["payload"].(map[string]any)
+ if !assert.True(t, ok) {
+ return
+ }
+ assert.Equal(t, []types.MessageID{"3A1", "3A2"}, payload["ids"])
+ assert.Equal(t, contact.String(), payload["chat_id"])
+ assert.Equal(t, own.String(), payload["from"], "device suffix must be stripped from the sender")
+ assert.Equal(t, "read-self", payload["receipt_type"])
+}