Group messages

Goal: let Clawd sit in WhatsApp groups, wake up only when pinged, and keep that thread separate from the personal DM session.

Current implementation (2025-12-03)

• Activation modes:
  text

  Copy

  mention
  (default) or
  text

  Copy

  always
  .
  text

  Copy

  mention
  requires a ping (real WhatsApp @-mentions via
  text

  Copy

  mentionedJids
  , safe regex patterns, or the bot’s E.164 anywhere in the text).
  text

  Copy

  always
  wakes the agent on every message but it should reply only when it can add meaningful value; otherwise it returns the exact silent token
  text

  Copy

  NO_REPLY
  /
  text

  Copy

  no_reply
  . Defaults can be set in config (
  text

  Copy

  channels.whatsapp.groups
  ) and overridden per group via
  text

  Copy

  /activation
  . When
  text

  Copy

  channels.whatsapp.groups
  is set, it also acts as a group allowlist (include
  text

  Copy

  "*"
  to allow all).
• Group policy:
  text

  Copy

  channels.whatsapp.groupPolicy
  controls whether group messages are accepted (
  text

  Copy

  open|disabled|allowlist
  ).
  text

  Copy

  allowlist
  uses
  text

  Copy

  channels.whatsapp.groupAllowFrom
  (fallback: explicit
  text

  Copy

  channels.whatsapp.allowFrom
  ). Default is
  text

  Copy

  allowlist
  (blocked until you add senders).
• Per-group sessions: session keys look like
  text

  Copy

  agent:<agentId>:whatsapp:group:<jid>
  so commands such as
  text

  Copy

  /verbose on
  ,
  text

  Copy

  /trace on
  , or
  text

  Copy

  /think high
  (sent as standalone messages) are scoped to that group; personal DM state is untouched. Heartbeats are skipped for group threads.
• Context injection: pending-only group messages (default 50) that did not trigger a run are prefixed under
  text

  Copy

  [Chat messages since your last reply - for context]
  , with the triggering line under
  text

  Copy

  [Current message - respond to this]
  . Messages already in the session are not re-injected.
• Sender surfacing: every group batch now ends with
  text

  Copy

  [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
  text

  Copy

  /activation
  changes the mode) we inject a short blurb into the system prompt like
  text

  Copy

  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 example (WhatsApp)

Add a

json5
Copy
{
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true },
      },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          historyLimit: 50,
          mentionPatterns: ["@?openclaw", "\\+?15555550123"],
        },
      },
    ],
  },
}

Notes:

• The regexes are case-insensitive and use the same safe-regex guardrails as other config regex surfaces; invalid patterns and unsafe nested repetition are ignored.
• WhatsApp still sends canonical mentions via
  text

  Copy

  mentionedJids
  when someone taps the contact, so the number fallback is rarely needed but is a useful safety net.

Activation command (owner-only)

Use the group chat command:

• text

  Copy

  /activation mention
• text

  Copy

  /activation always

Only the owner number (from

How to use

1. Add your WhatsApp account (the one running OpenClaw) to the group.
2. Say
   text

   Copy

   @openclaw …
   (or include the number). Only allowlisted senders can trigger it unless you set
   text

   Copy

   groupPolicy: "open"
   .
3. The agent prompt will include recent group context plus the trailing
   text

   Copy

   [from: …]
   marker so it can address the right person.
4. Session-level directives (
   text

   Copy

   /verbose on
   ,
   text

   Copy

   /trace on
   ,
   text

   Copy

   /think high
   ,
   text

   Copy

   /new
   or
   text

   Copy

   /reset
   ,
   text

   Copy

   /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
    text

    Copy

    @openclaw
    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
  text

  Copy

  --verbose
  ) to see
  text

  Copy

  inbound web message
  entries showing
  text

  Copy

  from: <groupJid>
  and the
  text

  Copy

  [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
  text

  Copy

  agent:<agentId>:whatsapp:group:<jid>
  in the session store (
  text

  Copy

  ~/.openclaw/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
  text

  Copy

  agents.defaults.typingMode
  . When visible replies use the default message-tool-only mode, typing starts immediately by default so group members can see the agent is working even if no automatic final reply is posted. Explicit typing-mode config still wins.

Related

• Groups
• Channel routing
• Broadcast groups