feat(whatsapp): add acknowledgment reactions

Overview

Implements automatic emoji reactions for WhatsApp messages, sent immediately upon receipt to provide instant user feedback. This is a WhatsApp-specific feature with granular per-chat-type control.

Changes

• Config: New whatsapp.ackReaction structure with {emoji, direct, group} options
• Logic: Reactions sent at start of processMessage(), before typing indicator
• Schema: Zod validation for new config structure
• Tests: 14 new unit tests covering all scenarios
• Docs: Comprehensive documentation in docs/providers/whatsapp.md
• Backward Compatibility: Old messages.ackReaction format still supported via fallback

Configuration

whatsapp:
  ackReaction:
    emoji: "👀"           # Emoji to use (empty = disabled)
    direct: true          # React in direct chats (default: true)
    group: "mentions"     # Group mode: "always" | "mentions" | "never" (default: "mentions")

Per-account override:

whatsapp:
  accounts:
    work:
      ackReaction:
        emoji: "✅"
        direct: false
        group: "always"

Behavior

• Timing: Reaction sent immediately upon message receipt (before bot reply)
• Direct chats: Controlled by direct boolean
• Group chats: Three modes:
  • "always": React to all messages
  • "mentions": Only when bot is @mentioned (respects requireMention: false)
  • "never": Never react in groups
• Error handling: Fire-and-forget with logging (reactions are non-critical)
• Participant support: Automatically includes sender JID for group reactions

Testing

Extensively tested with 5 scenarios:

1. ✅ direct=false, group="mentions" - No direct, groups with mention only
2. ✅ direct=true, group="always" - All direct, all groups
3. ✅ direct=true, group="never" - All direct, no groups
4. ✅ direct=false, group="always" - No direct, all groups
5. ✅ Multiple emojis tested (👀, ✅)

Unit tests: 14/14 passing
Build: Success, 0 linting errors
Live tested: Direct chats and group chats with various configurations

Files Changed

 docs/providers/whatsapp.md                  | +66 lines (new section + config map)
 src/config/types.ts                         | +18 lines (TypeDoc comments)
 src/config/zod-schema.ts                    | +32 lines (validation)
 src/web/auto-reply.ts                       | +56 lines (implementation)
 src/web/auto-reply.ack-reaction.test.ts     | 260 lines (complete rewrite)

Total: ~433 lines changed (5 files)

Breaking Changes

⚠️ Config location changed:

• Old: messages.ackReaction + messages.ackReactionScope
• New: whatsapp.ackReaction.{emoji, direct, group}

Migration is automatic via fallback, but users should update their configs:

Old format (still works):

messages:
  ackReaction: "👀"
  ackReactionScope: "all"  # or "direct", "group-all", "group-mentions"

New format (recommended):

whatsapp:
  ackReaction:
    emoji: "👀"
    direct: true
    group: "mentions"

Related

• Closes feat: WhatsApp acknowledgment reactions #628 (feature request issue)
• Similar to existing Telegram/Discord ack reactions
• Complements WhatsApp typing indicators

Checklist

• Implementation complete
• Tests written and passing (14/14)
• Documentation updated
• Backward compatibility maintained
• Build succeeds
• Linting passes (0 errors, 0 warnings)
• Live tested with multiple scenarios
• TypeDoc comments added
• Zod schema updated

Screenshots / Demo

Live tested with:

• ✅ Direct messages show immediate 👀 reaction
• ✅ Group messages with @mention show reaction
• ✅ Group messages without @mention (with requireMention: false) show reaction
• ✅ Different emojis work (👀, ✅, 🤖, etc.)
• ✅ Timing: reaction appears before bot starts typing