routes: is the preferred field name for gateway routing configuration — gateway runtime accepts both routing: and routes: interchangeably in YAML.
Message routing lets you send different types of messages to different AI agents. For example, direct messages go to your personal assistant, while group messages go to a support agent.
How Routing Works
Message Arrives
A user sends a message on Telegram, Discord, or Slack.
Context Detection
The gateway detects where the message came from — a DM, group, or channel.
Route Lookup
The gateway checks the routes table in gateway.yaml for that context.
Agent Handles Message
The matched agent receives the message and responds.
Route Contexts
| Context | Description | Example |
|---|
| dm | Direct / private message | User sends a DM to your bot |
| group | Group chat message | Message in a Telegram group or Discord server |
| channel | Channel message | Message in a Slack channel |
| default | Fallback for any unmatched context | Any message that doesn’t match above |
Always define a default route. It acts as a safety net — if a message comes from an unexpected context, the default agent handles it.
Configuration
Define routes in the channels section of gateway.yaml:
channels:
telegram:
token: ${TELEGRAM_BOT_TOKEN}
routes:
dm: personal # DMs → personal agent
group: support # Groups → support agent
default: personal # Everything else → personal agent
discord:
token: ${DISCORD_BOT_TOKEN}
routes:
dm: personal
group: support
default: personal
slack:
token: ${SLACK_BOT_TOKEN}
app_token: ${SLACK_APP_TOKEN}
routes:
dm: support
channel: support
default: support
whatsapp:
mode: web # or: token: ${WHATSAPP_ACCESS_TOKEN}
routes:
dm: personal
group: support
default: personal
Routing Examples
Route DMs to a personal assistant and group messages to support:agents:
personal:
instructions: "You are a helpful personal assistant"
model: gpt-4o-mini
support:
instructions: "You are a customer support agent"
model: gpt-4o
channels:
telegram:
token: ${TELEGRAM_BOT_TOKEN}
routes:
dm: personal
group: support
default: personal
Route all messages to one agent:agents:
assistant:
instructions: "You are a helpful assistant"
model: gpt-4o-mini
channels:
discord:
token: ${DISCORD_BOT_TOKEN}
routes:
default: assistant
Different agents per platform:agents:
telegram_agent:
instructions: "Telegram-optimized assistant"
model: gpt-4o-mini
slack_agent:
instructions: "Slack workspace assistant"
model: gpt-4o
channels:
telegram:
token: ${TELEGRAM_BOT_TOKEN}
routes:
default: telegram_agent
slack:
token: ${SLACK_BOT_TOKEN}
routes:
default: slack_agent
Multiple specialized bots on the same platform:agents:
cfo:
instructions: "You are a CFO agent. Help with financial analysis and budget planning."
model: gpt-4o-mini
ops:
instructions: "You are an ops agent. Help with system monitoring and deployment."
model: gpt-4o-mini
content:
instructions: "You are a content agent. Help with writing and content strategy."
model: gpt-4o-mini
channels:
telegram_cfo:
platform: telegram
token: ${TELEGRAM_CFO_BOT_TOKEN}
routes:
default: cfo
telegram_ops:
platform: telegram
token: ${TELEGRAM_OPS_BOT_TOKEN}
routes:
default: ops
telegram_content:
platform: telegram
token: ${TELEGRAM_CONTENT_BOT_TOKEN}
routes:
default: content
Note that the channel key (telegram_cfo) is now arbitrary — it no longer has to equal the platform name. The platform: key identifies the protocol.
Routing Flow Diagram
Routing is configured per channel. Each platform can have completely different routing rules — Telegram DMs can go to one agent while Discord DMs go to another.
