feat(whatsapp): send read receipts

[lobomfz]

What does this PR do?

Marks inbound allowlisted WhatsApp messages as read via Baileys, so senders see blue ticks and — more importantly in practice — the bot's own WhatsApp account stops piling up unread-message notifications on the host device. Today, running Hermes on a second WhatsApp number means every message I send it generates a lingering system notification on that account's phone/web, even after the bot has processed and replied. Marking the message as read immediately after it clears the allowlist resolves that.

The approach mirrors the existing BlueBubbles read-receipt flag (BLUEBUBBLES_SEND_READ_RECEIPTS) so the WhatsApp surface is consistent with the rest of the gateway: env var default-on, overridable via ~/.hermes/config.yaml, and decoupled from the send path.

Related Issue

Fixes #6055
Fixes #6539

(A different approach to the same problem is proposed in #8690; this PR adds an opt-out flag, uses fire-and-forget instead of await inside the message loop, places the receipt call explicitly after the fromMe and allowlist filters to avoid leaking reads to unauthorized senders, and updates the user docs.)

Type of Change

✨ New feature (non-breaking change that adds functionality)

Changes Made

• scripts/whatsapp-bridge/bridge.js — reads WHATSAPP_SEND_READ_RECEIPTS (default true); calls sock.readMessages([msg.key]) fire-and-forget after the fromMe/allowlist filters; errors logged only when WHATSAPP_DEBUG=true
• scripts/whatsapp-bridge/read_receipts.js — new pure helper shouldSendReadReceipt(msg, { enabled }), same extraction pattern as allowlist.js
• scripts/whatsapp-bridge/read_receipts.test.mjs — four node:test cases covering enabled, disabled, fromMe, and malformed inputs
• gateway/config.py — YAML key whatsapp.send_read_receipts bridged to WHATSAPP_SEND_READ_RECEIPTS env var, matching the existing require_mention / mention_patterns / free_response_chats pattern
• website/docs/reference/environment-variables.md, website/docs/user-guide/messaging/whatsapp.md, .env.example — documented env var and YAML option

How to Test

1. Start the bridge in bot mode against a second WhatsApp number and send a message from an allowlisted sender — the sender sees blue ticks and the bot's account no longer shows the message as unread.
2. Set WHATSAPP_SEND_READ_RECEIPTS=false (or whatsapp.send_read_receipts: false in ~/.hermes/config.yaml) and repeat — no blue ticks, message stays unread on the bot side.
3. From a sender not on the allowlist, send a message — no blue ticks appear (read confirmation is not leaked to unauthorized senders).
4. Run the bridge unit tests: node --test scripts/whatsapp-bridge/read_receipts.test.mjs scripts/whatsapp-bridge/allowlist.test.mjs — all 8 tests pass.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: Linux (CachyOS, kernel 6.19)

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A

Screenshots / Logs

N/A — change is a one-way WhatsApp protocol interaction; verification is visual (blue ticks on the sender side + cleared unread state on the bot side).

[teknium1]

Thanks for the focused implementation and the allowlist-aware placement.

• This automated hermes-sweeper review found that the PR makes WHATSAPP_SEND_READ_RECEIPTS a documented user-facing .env setting (.env.example; website/docs/reference/environment-variables.md). Read receipts are behavioral configuration, and the standing project policy requires those settings to live in config.yaml rather than new non-secret environment variables (AGENTS.md:102-106).
• The existing BlueBubbles precedent controls send_read_receipts from platforms.bluebubbles.extra and explicitly has no environment-variable counterpart (website/docs/user-guide/messaging/bluebubbles.md:121).
• The underlying Baileys read-receipt gap remains present on current main; this is not a rejection of the feature itself. If pursued, please re-scope it to a config.yaml-owned WhatsApp setting (for example platforms.whatsapp.extra) and bridge it internally to the Node process without documenting or exposing a new user-facing env var.

This is an automated hermes-sweeper review.

---

Closed as not-planned per standing maintainer policy (env-var-for-config). This is a design-direction decision, not a code-quality judgment — see the Contribution Rubric in AGENTS.md for what the project is looking for. If you believe this policy was misapplied to your change, comment here and a maintainer will take a look.