Bot Message Routing

Bot platform adapters now ship in the praisonai-bot package. praisonai bot serve still works exactly as documented here; for a standalone install see praisonai-bot Migration.

Quick Start

Define your agents

from praisonaiagents import Agent

personal_agent = Agent(name="personal", instructions="Handle personal questions.")
support_agent = Agent(name="support", instructions="Handle support requests.")
personal_agent.start("Route DMs to me, group messages to support.")

Serve with routing

praisonai bot serve

The user messages in a DM or group; the gateway matches the chat context and forwards the turn to the configured agent.

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

The user sends a message; the gateway detects the chat context, looks up the matching route, and forwards the turn to that agent.

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.

A user messages from a DM or group; the gateway detects the context, picks the matching agent, and returns its reply.

Context detection uses the detect_chat_type(platform, chat_id) helper under the hood. It classifies each message as "direct", "group", "channel", or "unknown" based on platform-specific chat ID patterns. See Platform-Aware Agents for the per-platform rules.

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

Personal + Support
Single Agent
Multi-Channel
Workforce (one platform, many roles)

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.

Going further: per-peer / per-role bindings

When chat-type routing isn’t specific enough — e.g. one specific user, a Discord role, or a specific channel id — use the priority-ordered bindings surface.

Gateway Route Bindings

Route by sender, role, channel id, or bot account — with priority ordering.

channels:
  telegram:
    routes:
      default: general
    bindings:
      - { peer: "12345678", agent: vip }
      - { role: support, agent: support }
      - { channel_id: "-100999", agent: ops }
      - { chat_type: dm, agent: assistant }

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.

Best Practices

Always define a default route

Set default on every channel so unexpected contexts (new group types, API changes) still reach an agent instead of failing silently.

Isolate agents by context

Route dm and group to different agents when personal and support workflows must not share memory or tools. See Platform-Aware Agents.

Use bindings for fine-grained routing

When chat-type routing is not enough, add priority-ordered Gateway Route Bindings for specific users, roles, or channel IDs.

Scope tools per route

Pair routing with Gateway Tool Policy so public group chats cannot invoke dangerous tools available to trusted DMs.

Gateway Route Bindings

Advanced routing by peer, role, channel id, and bot account — with priority.

Gateway Tool Policy

Scope the toolset per route — keep stranger DMs from running dangerous tools.

Dead-Target Registry

Gateway Route Bindings

​Quick Start

​How Routing Works

​Route Contexts

​Configuration

​Routing Examples

​Going further: per-peer / per-role bindings

Gateway Route Bindings

​Routing Flow Diagram

​Best Practices

​Related

Gateway Route Bindings

Gateway Tool Policy

Quick Start

How Routing Works

Route Contexts

Configuration

Routing Examples

Going further: per-peer / per-role bindings

Routing Flow Diagram

Best Practices

Related