Channel Routing & Broadcast Groups

+15 Mana ✨
OpenClaw Broadcast Groups(DOCUMENTATION)

Introduction

OpenClaw's channel routing goes beyond simple account-to-agent bindings. Broadcast groups let you send a single agent response to multiple channels simultaneously, and routing rules can include conditions based on message metadata.

Key Concepts

  • Broadcast Group: A named group of channels that all receive a copy of the agent's response. Useful for cross-platform announcements.
  • Routing Rules: Conditional logic that determines which agent handles a message based on metadata like channel type, sender role, or message content.
  • Channel Priority: When multiple channels are connected, priority determines which channel gets the response first.
  • Fallback Channel: A backup channel that receives messages if the primary channel is unavailable.

Real World Context

A DevOps team wants deployment notifications sent to both Slack and Discord simultaneously. When the deployment agent finishes a deploy, the response goes to a broadcast group containing both the Slack ops channel and the Discord devops channel. Team members see the notification on whichever platform they prefer.

Deep Dive

Broadcast groups are defined in the gateway configuration:

json
{
  "broadcastGroups": {
    "ops-notifications": {
      "channels": [
        { "type": "slack", "accountId": "slack:ops-workspace", "target": "#deployments" },
        { "type": "discord", "accountId": "discord:devops-bot", "target": "channel-id-123" }
      ]
    },
    "all-hands": {
      "channels": [
        { "type": "slack", "accountId": "slack:main", "target": "#general" },
        { "type": "discord", "accountId": "discord:main", "target": "channel-id-456" },
        { "type": "telegram", "accountId": "telegram:company-bot", "target": "group-id-789" }
      ]
    }
  }
}

This defines two broadcast groups. The ops-notifications group sends to Slack and Discord simultaneously. The all-hands group broadcasts to Slack, Discord, and Telegram for company-wide announcements.

The agent can target a broadcast group in its response, and the gateway fans the message out to all channels in the group. Each channel receives a platform-appropriate version of the message (Slack gets rich blocks, Discord gets embeds, Telegram gets markdown).

Routing rules can also include conditions beyond simple account matching:

json
{
  "routing": {
    "rules": [
      {
        "match": { "channel": "discord", "hasRole": "admin" },
        "agent": "admin-bot"
      },
      {
        "match": { "channel": "discord" },
        "agent": "general-bot"
      }
    ]
  }
}

This rule set routes Discord messages from admins to the admin-bot and all other Discord messages to the general-bot. Rules are evaluated top-to-bottom, and the first match wins.

Common Pitfalls

  1. Creating circular broadcast loops — If a broadcast group includes a channel that the agent also listens on, the agent's own broadcast can trigger a new message, creating an infinite loop.
  2. Ignoring platform message limits — Each platform has different message size limits (WhatsApp: 4K, Discord: 2K). A broadcast message that fits on one platform may be truncated on another.

Best Practices

  1. Test broadcast groups with a dry-run — Send a test message to each group before using them in production to verify all channels receive correctly formatted messages.
  2. Use broadcast groups sparingly — Not every message needs to go everywhere. Reserve broadcast groups for important notifications.

Summary

  • Broadcast groups send agent responses to multiple channels simultaneously
  • Each channel in a group receives a platform-appropriate version of the message
  • Routing rules support conditional matching based on channel, roles, and metadata
  • Rules are evaluated top-to-bottom with first-match-wins semantics
  • Avoid circular broadcast loops and account for platform message size limits
✓ Completed