GOWA - WhatsApp REST API with support for UI, Multi Account, Webhooks, and MCP, and Chatwoot. Built with Golang for efficient memory use.
Go botgogolanggolang-whatsappgolang-whatsapp-apirestrest-apiwhatsappwhatsapp-apiwhatsapp-api-gowhatsapp-multi-devicewhatsapp-web-multi-device
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.mdindex 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.mdindex 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 jobskeyed by device, event name, and WhatsApp message ID. Initialize the client registrybefore 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.goindex 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.gonew file mode 100644index 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"])+}