OpenClaw WhatsApp Group Chat Setup Guide

whatsapp-group-setup-guide.md

OpenClaw WhatsApp Group Chat Setup Guide

A quick guide to setting up OpenClaw in WhatsApp group chats.

Why Use Groups?

• Shared context: Multiple people can interact with your assistant in one place
• Family/team assistant: Great for household tasks, shared reminders, trip planning
• Less context switching: No need to DM the bot separately

Prerequisites

• OpenClaw gateway running with WhatsApp connected
• Your WhatsApp number linked via openclaw channels login
• The bot added to a WhatsApp group

Step 1: Find Your Group JID

WhatsApp groups are identified by a JID (Jabber ID) that looks like: 123456789012345678@g.us

To find it:

1. Send a message in the group (with or without @mentioning the bot)
2. Check active sessions:

   openclaw sessions list

3. Look for a session with whatsapp:group: in the key — the JID is the part after group:

Alternative: If you have access to the agent, ask it to run:

sessions_list with messageLimit: 1

And look for group sessions in the output.

Step 2: Configure the Group

Add the group JID to your ~/.openclaw/openclaw.json:

{
  "channels": {
    "whatsapp": {
      "groupPolicy": "allowlist",
      "groups": {
        "123456789012345678@g.us": {}
      }
    }
  }
}

Group Options

Each group can have these settings:

{
  "groups": {
    "123456789012345678@g.us": {
      "requireMention": true
    }
  }
}

Option	Default	Description
requireMention	true	If true, bot only responds when @mentioned. Set to false to respond to all messages.

Step 3: Restart the Gateway

After editing config, restart for changes to take effect:

openclaw gateway restart

Or if using the config tool:

openclaw config set channels.whatsapp.groups.'123456789012345678@g.us'.requireMention false

Configuration Examples

Single Group with Mention Required (Default)

{
  "channels": {
    "whatsapp": {
      "groupPolicy": "allowlist",
      "groups": {
        "123456789012345678@g.us": {}
      }
    }
  }
}

Bot responds only when @mentioned in the group.

Single Group, Always Active

{
  "channels": {
    "whatsapp": {
      "groupPolicy": "allowlist",
      "groups": {
        "123456789012345678@g.us": {
          "requireMention": false
        }
      }
    }
  }
}

Bot responds to ALL messages in the group (use with caution in busy groups!).

Multiple Groups

{
  "channels": {
    "whatsapp": {
      "groupPolicy": "allowlist",
      "groups": {
        "123456789012345678@g.us": {
          "requireMention": false
        },
        "987654321098765432@g.us": {
          "requireMention": true
        }
      }
    }
  }
}

Allow All Groups (Wildcard)

{
  "channels": {
    "whatsapp": {
      "groupPolicy": "allowlist",
      "groups": {
        "*": {}
      }
    }
  }
}

⚠️ Caution: This allows the bot in ALL groups it's added to. Mention is still required by default.

Troubleshooting

Bot doesn't respond in group

1. Check JID is correct: Group JIDs end in @g.us
2. Check groupPolicy: Must be "allowlist" with your group in groups, or use "*" wildcard
3. Check mention: If requireMention is true (default), you must @mention the bot
4. Restart gateway: Config changes need a restart

Finding the bot's name for @mentions

The bot appears in the group under whatever name the WhatsApp account is saved as on participants' phones. If you saved the number as "Assistant", that's how you @mention it.

Outbound works but inbound doesn't

This usually means the group JID is correct but mention detection isn't working:

• Try setting requireMention: false temporarily to confirm messages are reaching the bot
• Check the bot's WhatsApp contact name matches what you're typing for @mentions

Session exists but 0 messages processed

The group is recognized but messages aren't being forwarded. Usually fixed by:

1. Explicitly adding the group JID (instead of "*" wildcard)
2. Setting requireMention: false
3. Restarting the gateway

Tips

• Start with requireMention: true in busy groups to avoid spam
• Use requireMention: false for small family/private groups where you want the bot always listening
• Each group gets its own session — context is isolated per group
• The bot sees message history when joining a conversation (configurable via historyLimit)

Related Docs

• WhatsApp Channel Documentation
• Multi-Agent Routing
• Session Scoping

---

Guide created for OpenClaw users. Questions? Join the Discord.