Broadcast Groups
Broadcast a WhatsApp message to multiple agents
Experimental
Broadcast Groups enable multiple agents to process and respond to same message simultaneously. This allows you to create specialized agent teams that work together in a single WhatsApp group or DM — all using one phone number.
Current scope: WhatsApp only (web channel).
Broadcast groups are evaluated after channel allowlists and group activation rules. In WhatsApp groups, this means broadcasts happen when OpenClaw would normally reply (for example: on mention, depending on your group settings).
Use Cases
1. Specialized Agent Teams
Deploy multiple agents with atomic, focused responsibilities:
Group: "Development Team" Agents: - CodeReviewer (reviews code snippets) - DocumentationBot (generates docs) - SecurityAuditor (checks for vulnerabilities) - TestGenerator (suggests test cases)
Each agent processes the same message and provides its specialized perspective.
2. Multi-Language Support
Group: "International Support" Agents: - Agent_EN (responds in English) - Agent_DE (responds in German) - Agent_ES (responds in Spanish)
3. Quality Assurance Workflows
Group: "Customer Support" Agents: - SupportAgent (provides answer) - QAAgent (reviews quality, only responds if issues found)
4. Task Automation
Group: "Project Management" Agents: - TaskTracker (updates task database) - TimeLogger (logs time spent) - ReportGenerator (creates summaries)
Configuration
Add a top-level ''broadcast'' section (next to ''bindings''). Keys are WhatsApp peer ids:
- group chats: group JID (e.g. ''[email protected]'')
- DMs: E.164 phone number (e.g. ''+15551234567'')
{
"broadcast": {
"[email protected]": ["alfred", "baerbel", "assistant3"]
}
}Result: When OpenClaw would reply in this chat, it will run all three agents.
Processing Strategy
Control how agents process messages:
Parallel (Default): All agents process simultaneously:
{
"broadcast": {
"strategy": "parallel",
"[email protected]": ["alfred", "baerbel"]
}
}Sequential: Agents process in order (one waits for previous to finish):
{
"broadcast": {
"strategy": "sequential",
"[email protected]": ["alfred", "baerbel"]
}
}Complete Example
{
"agents": {
"list": [
{
"id": "code-reviewer",
"name": "Code Reviewer",
"workspace": "/path/to/code-reviewer",
"sandbox": { "mode": "all" }
},
{
"id": "security-auditor",
"name": "Security Auditor",
"workspace": "/path/to/security-auditor",
"sandbox": { "mode": "all" }
},
{
"id": "docs-generator",
"name": "Documentation Generator",
"workspace": "/path/to/docs-generator",
"sandbox": { "mode": "all" }
}
]
},
"broadcast": {
"strategy": "parallel",
"[email protected]": ["code-reviewer", "security-auditor", "docs-generator"],
"[email protected]": ["support-en", "support-de"],
"+15555550123": ["assistant", "logger"]
}
}How It Works
Message Flow
1. Incoming message arrives in a WhatsApp group
2. ''Broadcast check'': System checks if peer ID is in ''broadcast''
3. If in broadcast list:
- All listed agents process message
- Each agent has its own session key and isolated context
- Agents process in parallel (default) or sequentially
4. If not in broadcast list:
- Normal routing applies (first matching binding)
Note: broadcast groups do not bypass channel allowlists or group activation rules (mentions/commands/etc). They only change which agents run when a message is eligible for processing.
Session Isolation
Each agent in a broadcast group maintains completely separate:
- ''Session keys'' (''agent:alfred:whatsapp:group:120363...'' vs ''agent:baerbel:whatsapp:group:120363...'')
- Conversation history (agent doesn't see other agents' messages)
- Workspace (separate sandboxes if configured)
- Tool access (different allow/deny lists)
- Memory/context (separate IDENTITY.md, SOUL.md, etc.)
- Group context buffer (recent group messages used for context) is shared per peer, so all broadcast agents see the same context when triggered
This allows each agent to have:
- Different personalities
- Different tool access (e.g., read-only vs. read-write)
Best Practices
1. Keep Agents Focused
Design each agent with a single, clear responsibility.
2. Use Descriptive Names
Make it clear what each agent does.
3. Configure Different Tool Access
Give agents only the tools they need.
4. Monitor Performance
With many agents, consider using ''"strategy": "parallel"'', limiting group size, and using faster models.
5. Handle Failures Gracefully
Agents fail independently. One agent's error doesn't block others.
Troubleshooting
Agents Not Responding
Check:
1. Agent IDs exist in ''agents.list''
2. Peer ID format is correct (e.g. ''[email protected]'')
3. Agents are not in deny lists
Debug:
tail -f ~/.openclaw/logs/gateway.log | grep broadcast
Only One Agent Responding
Cause: Peer ID might be in ''bindings'' but not ''broadcast''.
Fix: Add to broadcast config or remove from bindings.