clawdbot/docs/group-messages.md

Group Messages Plan

Goal: Enable warelay’s web provider to participate in WhatsApp group chats, replying only when mentioned and using recent group context. Keep personal (1:1) sessions separate from group sessions.

Scope & Constraints

• Web provider only; Twilio untouched.
• Default-safe: no unsolicited group replies unless mentioned.
• Preserve existing direct-chat behavior and batching.

Design Decisions

• Config: Add inbound.groupChat with:
  • requireMention (default: true)
  • mentionPatterns (array of regex strings; optional)
  • historyLimit (default: 50)
• Conversation identity:
  • Direct chats keyed by E.164 (+123).
  • Group chats keyed by raw group JID (<id>@g.us) and labeled chatType: "group".
• Mention detection:
  • Trust Baileys contextInfo.mentionedJid vs our own self JID.
  • Fallback regex match on body using mentionPatterns.
• Group context:
  • Maintain per-group ring buffer of messages since last bot reply (cap historyLimit).
  • When mentioned, prepend [Chat messages since your last reply] section with sender: body, then current message.
  • Clear buffer after replying.
• Gating:
  • If requireMention and no mention detected, store in buffer only; no reply.
  • Allow opt-out via requireMention: false.
• Allow list:
  • Apply inbound.allowFrom to the participant (senderE164), not the group ID. Same-phone bypass preserved.
• Heartbeats:
  • Skip reply heartbeats when the last inbound was a group chat; connection heartbeat still runs.
• Sessions:
  • Session key uses group conversation id so group threads don’t collide with personal sessions.

Implementation Steps

1. Config/schema/docs
   • Extend WarelayConfig + Zod schema with inbound.groupChat.
   • Add defaults and README config table entry.
2. Inbound plumbing (src/web/inbound.ts)
   • Detect groups, surface chatId, chatType, senderJid, senderE164, senderName, and mentionedJids.
   • Apply allowFrom to participant; keep mark-read with participant.
3. Auto-reply loop (src/web/auto-reply.ts)
   • Key batching/history by conversation id (group vs direct).
   • Implement mention gating and context injection from history.
   • Clear history after reply; cap history length.
   • Guard heartbeats for groups.
   • Ensure session key uses conversation id for groups.
4. Tests
   • Inbound: group passthrough + allowFrom on participant + mention capture.
   • Auto-reply: mention gating, history accumulation/clear, batching by group, session separation, heartbeat skip for groups.

Open Questions / TODO

• Should we expose a configurable bot self-name for pattern defaults (e.g., auto-generate mentionPatterns from selfJid/local number)? For now, rely on explicit config + WhatsApp mentions.
• Do we need a max age for stored history (time-based) in addition to count-based cap? Default to count-only unless it becomes noisy.