{
  "title": "Broadcast Groups",
  "content": "**Status:** Experimental\\\n**Version:** Added in 2026.1.9\n\nBroadcast Groups enable multiple agents to process and respond to the 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.\n\nCurrent scope: **WhatsApp only** (web channel).\n\nBroadcast 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).\n\n### 1. Specialized Agent Teams\n\nDeploy multiple agents with atomic, focused responsibilities:\n\nEach agent processes the same message and provides its specialized perspective.\n\n### 2. Multi-Language Support\n\n### 3. Quality Assurance Workflows\n\n### 4. Task Automation\n\nAdd a top-level `broadcast` section (next to `bindings`). Keys are WhatsApp peer ids:\n\n* group chats: group JID (e.g. `120363403215116621@g.us`)\n* DMs: E.164 phone number (e.g. `+15551234567`)\n\n**Result:** When OpenClaw would reply in this chat, it will run all three agents.\n\n### Processing Strategy\n\nControl how agents process messages:\n\n#### Parallel (Default)\n\nAll agents process simultaneously:\n\nAgents process in order (one waits for previous to finish):\n\n1. **Incoming message** arrives in a WhatsApp group\n2. **Broadcast check**: System checks if peer ID is in `broadcast`\n3. **If in broadcast list**:\n   * All listed agents process the message\n   * Each agent has its own session key and isolated context\n   * Agents process in parallel (default) or sequentially\n4. **If not in broadcast list**:\n   * Normal routing applies (first matching binding)\n\nNote: 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.\n\n### Session Isolation\n\nEach agent in a broadcast group maintains completely separate:\n\n* **Session keys** (`agent:alfred:whatsapp:group:120363...` vs `agent:baerbel:whatsapp:group:120363...`)\n* **Conversation history** (agent doesn't see other agents' messages)\n* **Workspace** (separate sandboxes if configured)\n* **Tool access** (different allow/deny lists)\n* **Memory/context** (separate IDENTITY.md, SOUL.md, etc.)\n* **Group context buffer** (recent group messages used for context) is shared per peer, so all broadcast agents see the same context when triggered\n\nThis allows each agent to have:\n\n* Different personalities\n* Different tool access (e.g., read-only vs. read-write)\n* Different models (e.g., opus vs. sonnet)\n* Different skills installed\n\n### Example: Isolated Sessions\n\nIn group `120363403215116621@g.us` with agents `[\"alfred\", \"baerbel\"]`:\n\n**Alfred's context:**\n\n**Bärbel's context:**\n\n### 1. Keep Agents Focused\n\nDesign each agent with a single, clear responsibility:\n\n✅ **Good:** Each agent has one job\\\n❌ **Bad:** One generic \"dev-helper\" agent\n\n### 2. Use Descriptive Names\n\nMake it clear what each agent does:\n\n### 3. Configure Different Tool Access\n\nGive agents only the tools they need:\n\n### 4. Monitor Performance\n\nWith many agents, consider:\n\n* Using `\"strategy\": \"parallel\"` (default) for speed\n* Limiting broadcast groups to 5-10 agents\n* Using faster models for simpler agents\n\n### 5. Handle Failures Gracefully\n\nAgents fail independently. One agent's error doesn't block others:\n\nBroadcast groups currently work with:\n\n* ✅ WhatsApp (implemented)\n* 🚧 Telegram (planned)\n* 🚧 Discord (planned)\n* 🚧 Slack (planned)\n\nBroadcast groups work alongside existing routing:\n\n* `GROUP_A`: Only alfred responds (normal routing)\n* `GROUP_B`: agent1 AND agent2 respond (broadcast)\n\n**Precedence:** `broadcast` takes priority over `bindings`.\n\n### Agents Not Responding\n\n1. Agent IDs exist in `agents.list`\n2. Peer ID format is correct (e.g., `120363403215116621@g.us`)\n3. Agents are not in deny lists\n\n### Only One Agent Responding\n\n**Cause:** Peer ID might be in `bindings` but not `broadcast`.\n\n**Fix:** Add to broadcast config or remove from bindings.\n\n### Performance Issues\n\n**If slow with many agents:**\n\n* Reduce number of agents per group\n* Use lighter models (sonnet instead of opus)\n* Check sandbox startup time\n\n### Example 1: Code Review Team\n\n**User sends:** Code snippet\\\n**Responses:**\n\n* code-formatter: \"Fixed indentation and added type hints\"\n* security-scanner: \"⚠️ SQL injection vulnerability in line 12\"\n* test-coverage: \"Coverage is 45%, missing tests for error cases\"\n* docs-checker: \"Missing docstring for function `process_data`\"\n\n### Example 2: Multi-Language Support\n\n* `strategy` (optional): How to process agents\n  * `\"parallel\"` (default): All agents process simultaneously\n  * `\"sequential\"`: Agents process in array order\n* `[peerId]`: WhatsApp group JID, E.164 number, or other peer ID\n  * Value: Array of agent IDs that should process messages\n\n1. **Max agents:** No hard limit, but 10+ agents may be slow\n2. **Shared context:** Agents don't see each other's responses (by design)\n3. **Message ordering:** Parallel responses may arrive in any order\n4. **Rate limits:** All agents count toward WhatsApp rate limits\n\n## Future Enhancements\n\n* [ ] Shared context mode (agents see each other's responses)\n* [ ] Agent coordination (agents can signal each other)\n* [ ] Dynamic agent selection (choose agents based on message content)\n* [ ] Agent priorities (some agents respond before others)\n\n* [Multi-Agent Configuration](/multi-agent-sandbox-tools)\n* [Routing Configuration](/concepts/channel-routing)\n* [Session Management](/concepts/sessions)",
  "code_samples": [
    {
      "code": "Group: \"Development Team\"\nAgents:\n  - CodeReviewer (reviews code snippets)\n  - DocumentationBot (generates docs)\n  - SecurityAuditor (checks for vulnerabilities)\n  - TestGenerator (suggests test cases)",
      "language": "unknown"
    },
    {
      "code": "Group: \"International Support\"\nAgents:\n  - Agent_EN (responds in English)\n  - Agent_DE (responds in German)\n  - Agent_ES (responds in Spanish)",
      "language": "unknown"
    },
    {
      "code": "Group: \"Customer Support\"\nAgents:\n  - SupportAgent (provides answer)\n  - QAAgent (reviews quality, only responds if issues found)",
      "language": "unknown"
    },
    {
      "code": "Group: \"Project Management\"\nAgents:\n  - TaskTracker (updates task database)\n  - TimeLogger (logs time spent)\n  - ReportGenerator (creates summaries)",
      "language": "unknown"
    },
    {
      "code": "**Result:** When OpenClaw would reply in this chat, it will run all three agents.\n\n### Processing Strategy\n\nControl how agents process messages:\n\n#### Parallel (Default)\n\nAll agents process simultaneously:",
      "language": "unknown"
    },
    {
      "code": "#### Sequential\n\nAgents process in order (one waits for previous to finish):",
      "language": "unknown"
    },
    {
      "code": "### Complete Example",
      "language": "unknown"
    },
    {
      "code": "## How It Works\n\n### Message Flow\n\n1. **Incoming message** arrives in a WhatsApp group\n2. **Broadcast check**: System checks if peer ID is in `broadcast`\n3. **If in broadcast list**:\n   * All listed agents process the message\n   * Each agent has its own session key and isolated context\n   * Agents process in parallel (default) or sequentially\n4. **If not in broadcast list**:\n   * Normal routing applies (first matching binding)\n\nNote: 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.\n\n### Session Isolation\n\nEach agent in a broadcast group maintains completely separate:\n\n* **Session keys** (`agent:alfred:whatsapp:group:120363...` vs `agent:baerbel:whatsapp:group:120363...`)\n* **Conversation history** (agent doesn't see other agents' messages)\n* **Workspace** (separate sandboxes if configured)\n* **Tool access** (different allow/deny lists)\n* **Memory/context** (separate IDENTITY.md, SOUL.md, etc.)\n* **Group context buffer** (recent group messages used for context) is shared per peer, so all broadcast agents see the same context when triggered\n\nThis allows each agent to have:\n\n* Different personalities\n* Different tool access (e.g., read-only vs. read-write)\n* Different models (e.g., opus vs. sonnet)\n* Different skills installed\n\n### Example: Isolated Sessions\n\nIn group `120363403215116621@g.us` with agents `[\"alfred\", \"baerbel\"]`:\n\n**Alfred's context:**",
      "language": "unknown"
    },
    {
      "code": "**Bärbel's context:**",
      "language": "unknown"
    },
    {
      "code": "## Best Practices\n\n### 1. Keep Agents Focused\n\nDesign each agent with a single, clear responsibility:",
      "language": "unknown"
    },
    {
      "code": "✅ **Good:** Each agent has one job\\\n❌ **Bad:** One generic \"dev-helper\" agent\n\n### 2. Use Descriptive Names\n\nMake it clear what each agent does:",
      "language": "unknown"
    },
    {
      "code": "### 3. Configure Different Tool Access\n\nGive agents only the tools they need:",
      "language": "unknown"
    },
    {
      "code": "### 4. Monitor Performance\n\nWith many agents, consider:\n\n* Using `\"strategy\": \"parallel\"` (default) for speed\n* Limiting broadcast groups to 5-10 agents\n* Using faster models for simpler agents\n\n### 5. Handle Failures Gracefully\n\nAgents fail independently. One agent's error doesn't block others:",
      "language": "unknown"
    },
    {
      "code": "## Compatibility\n\n### Providers\n\nBroadcast groups currently work with:\n\n* ✅ WhatsApp (implemented)\n* 🚧 Telegram (planned)\n* 🚧 Discord (planned)\n* 🚧 Slack (planned)\n\n### Routing\n\nBroadcast groups work alongside existing routing:",
      "language": "unknown"
    },
    {
      "code": "* `GROUP_A`: Only alfred responds (normal routing)\n* `GROUP_B`: agent1 AND agent2 respond (broadcast)\n\n**Precedence:** `broadcast` takes priority over `bindings`.\n\n## Troubleshooting\n\n### Agents Not Responding\n\n**Check:**\n\n1. Agent IDs exist in `agents.list`\n2. Peer ID format is correct (e.g., `120363403215116621@g.us`)\n3. Agents are not in deny lists\n\n**Debug:**",
      "language": "unknown"
    },
    {
      "code": "### Only One Agent Responding\n\n**Cause:** Peer ID might be in `bindings` but not `broadcast`.\n\n**Fix:** Add to broadcast config or remove from bindings.\n\n### Performance Issues\n\n**If slow with many agents:**\n\n* Reduce number of agents per group\n* Use lighter models (sonnet instead of opus)\n* Check sandbox startup time\n\n## Examples\n\n### Example 1: Code Review Team",
      "language": "unknown"
    },
    {
      "code": "**User sends:** Code snippet\\\n**Responses:**\n\n* code-formatter: \"Fixed indentation and added type hints\"\n* security-scanner: \"⚠️ SQL injection vulnerability in line 12\"\n* test-coverage: \"Coverage is 45%, missing tests for error cases\"\n* docs-checker: \"Missing docstring for function `process_data`\"\n\n### Example 2: Multi-Language Support",
      "language": "unknown"
    },
    {
      "code": "## API Reference\n\n### Config Schema",
      "language": "unknown"
    }
  ],
  "headings": [
    {
      "level": "h2",
      "text": "Overview",
      "id": "overview"
    },
    {
      "level": "h2",
      "text": "Use Cases",
      "id": "use-cases"
    },
    {
      "level": "h3",
      "text": "1. Specialized Agent Teams",
      "id": "1.-specialized-agent-teams"
    },
    {
      "level": "h3",
      "text": "2. Multi-Language Support",
      "id": "2.-multi-language-support"
    },
    {
      "level": "h3",
      "text": "3. Quality Assurance Workflows",
      "id": "3.-quality-assurance-workflows"
    },
    {
      "level": "h3",
      "text": "4. Task Automation",
      "id": "4.-task-automation"
    },
    {
      "level": "h2",
      "text": "Configuration",
      "id": "configuration"
    },
    {
      "level": "h3",
      "text": "Basic Setup",
      "id": "basic-setup"
    },
    {
      "level": "h3",
      "text": "Processing Strategy",
      "id": "processing-strategy"
    },
    {
      "level": "h3",
      "text": "Complete Example",
      "id": "complete-example"
    },
    {
      "level": "h2",
      "text": "How It Works",
      "id": "how-it-works"
    },
    {
      "level": "h3",
      "text": "Message Flow",
      "id": "message-flow"
    },
    {
      "level": "h3",
      "text": "Session Isolation",
      "id": "session-isolation"
    },
    {
      "level": "h3",
      "text": "Example: Isolated Sessions",
      "id": "example:-isolated-sessions"
    },
    {
      "level": "h2",
      "text": "Best Practices",
      "id": "best-practices"
    },
    {
      "level": "h3",
      "text": "1. Keep Agents Focused",
      "id": "1.-keep-agents-focused"
    },
    {
      "level": "h3",
      "text": "2. Use Descriptive Names",
      "id": "2.-use-descriptive-names"
    },
    {
      "level": "h3",
      "text": "3. Configure Different Tool Access",
      "id": "3.-configure-different-tool-access"
    },
    {
      "level": "h3",
      "text": "4. Monitor Performance",
      "id": "4.-monitor-performance"
    },
    {
      "level": "h3",
      "text": "5. Handle Failures Gracefully",
      "id": "5.-handle-failures-gracefully"
    },
    {
      "level": "h2",
      "text": "Compatibility",
      "id": "compatibility"
    },
    {
      "level": "h3",
      "text": "Providers",
      "id": "providers"
    },
    {
      "level": "h3",
      "text": "Routing",
      "id": "routing"
    },
    {
      "level": "h2",
      "text": "Troubleshooting",
      "id": "troubleshooting"
    },
    {
      "level": "h3",
      "text": "Agents Not Responding",
      "id": "agents-not-responding"
    },
    {
      "level": "h3",
      "text": "Only One Agent Responding",
      "id": "only-one-agent-responding"
    },
    {
      "level": "h3",
      "text": "Performance Issues",
      "id": "performance-issues"
    },
    {
      "level": "h2",
      "text": "Examples",
      "id": "examples"
    },
    {
      "level": "h3",
      "text": "Example 1: Code Review Team",
      "id": "example-1:-code-review-team"
    },
    {
      "level": "h3",
      "text": "Example 2: Multi-Language Support",
      "id": "example-2:-multi-language-support"
    },
    {
      "level": "h2",
      "text": "API Reference",
      "id": "api-reference"
    },
    {
      "level": "h3",
      "text": "Config Schema",
      "id": "config-schema"
    },
    {
      "level": "h3",
      "text": "Fields",
      "id": "fields"
    },
    {
      "level": "h2",
      "text": "Limitations",
      "id": "limitations"
    },
    {
      "level": "h2",
      "text": "Future Enhancements",
      "id": "future-enhancements"
    },
    {
      "level": "h2",
      "text": "See Also",
      "id": "see-also"
    }
  ],
  "url": "llms-txt#broadcast-groups",
  "links": []
}