Skip to main content

​
Group messages (web provider)

Goal: let Clawd sit in WhatsApp groups, wake up only when pinged, and keep that thread separate from the personal DM session. Note: routing.groupChat.mentionPatterns is now used by Telegram/Discord/Slack/iMessage as well; this doc focuses on WhatsApp-specific behavior. For multi-agent setups, you can override per agent with routing.agents.<agentId>.mentionPatterns.

​
What’s implemented (2025-12-03)

  • Activation modes: mention (default) or always. mention requires a ping (real WhatsApp @-mentions via mentionedJids, regex patterns, or the bot’s E.164 anywhere in the text). always wakes the agent on every message but it should reply only when it can add meaningful value; otherwise it returns the silent token NO_REPLY. Defaults can be set in config (whatsapp.groups) and overridden per group via /activation. When whatsapp.groups is set, it also acts as a group allowlist (include "*" to allow all).
  • Group policy: whatsapp.groupPolicy controls whether group messages are accepted (open|disabled|allowlist). allowlist uses whatsapp.groupAllowFrom (fallback: explicit whatsapp.allowFrom).
  • Per-group sessions: session keys look like whatsapp:group:<jid> so commands such as /verbose on or /think high (sent as standalone messages) are scoped to that group; personal DM state is untouched. Heartbeats are skipped for group threads.
  • Context injection: last N (default 50) group messages are prefixed under [Chat messages since your last reply - for context], with the triggering line under [Current message - respond to this].
  • Sender surfacing: every group batch now ends with [from: Sender Name (+E164)] so Pi knows who is speaking.
  • Ephemeral/view-once: we unwrap those before extracting text/mentions, so pings inside them still trigger.
  • Group system prompt: on the first turn of a group session (and whenever /activation changes the mode) we inject a short blurb into the system prompt like You are replying inside the WhatsApp group "<subject>". Group members: Alice (+44...), Bob (+43...), … Activation: trigger-only … Address the specific sender noted in the message context. If metadata isn’t available we still tell the agent it’s a group chat.

​
Config for Clawd UK (+447700900123)

Add a groupChat block to ~/.clawdbot/clawdbot.json so display-name pings work even when WhatsApp strips the visual @ in the text body: 
{
  "whatsapp": {
    "groups": {
      "*": { "requireMention": true }
    }
  },
  "routing": {
    "groupChat": {
      "historyLimit": 50,
      "mentionPatterns": [
        "@?clawd",
        "@?clawd\\s*uk",
        "@?clawdbot",
        "\\+?447700900123"
      ]
    }
  }
}
Notes:
  • The regexes are case-insensitive; they cover @clawd, @clawd uk, clawdbot, and the raw number with or without +/spaces.
  • WhatsApp still sends canonical mentions via mentionedJids when someone taps the contact, so the number fallback is rarely needed but is a good safety net.

​
Activation command (owner-only)

Use the group chat command:
  • /activation mention
  • /activation always
Only the owner number (from whatsapp.allowFrom, or the bot’s own E.164 when unset) can change this. Send /status as a standalone message in the group to see the current activation mode.

​
How to use

  1. Add Clawd UK (+447700900123) to the group.
  2. Say @clawd … (or @clawd uk, @clawdbot, or include the number). Anyone in the group can trigger it.
  3. The agent prompt will include recent group context plus the trailing [from: …] marker so it can address the right person.
  4. Session-level directives (/verbose on, /think high, /new or /reset, /compact) apply only to that group’s session; send them as standalone messages so they register. Your personal DM session remains independent.

​
Testing / verification

  • Manual smoke:
    • Send an @clawd ping in the group and confirm a reply that references the sender name.
    • Send a second ping and verify the history block is included then cleared on the next turn.
  • Check gateway logs (run with --verbose) to see inbound web message entries showing from: <groupJid> and the [from: …] suffix.

​
Known considerations

  • Heartbeats are intentionally skipped for groups to avoid noisy broadcasts.
  • Echo suppression uses the combined batch string; if you send identical text twice without mentions, only the first will get a response.
  • Session store entries will appear as agent:<agentId>:whatsapp:group:<jid> in the session store (~/.clawdbot/agents/<agentId>/sessions/sessions.json by default); a missing entry just means the group hasn’t triggered a run yet.
  • Typing indicators in groups follow agent.typingMode (default: message when unmentioned).