Bot Message Routing

Route messages from different chat contexts (DMs, groups, channels) to specific AI agents.

Quick Start

1. 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.")

2. 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.

1. Message Arrives

   A user sends a message on Telegram, Discord, or Slack.

2. Context Detection

   The gateway detects where the message came from — a DM, group, or channel.

3. Route Lookup

   The gateway checks the routes table in gateway.yaml for that context.

4. 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.

Route Contexts

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

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

agents:
  assistant:
    instructions: "You are a helpful assistant"
    model: gpt-4o-mini

channels:
  discord:
    token: ${DISCORD_BOT_TOKEN}
    routes:
      default: assistant

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

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

Going further: per-peer, per-role, per-channel, per-thread or per-server bindings

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

channels:
  telegram:
    routes:
      default: general
    bindings:
      - { peer: "12345678", agent: vip }
      - { role: support,    agent: support }
      - { channel_id: "-100999", agent: ops }
      - { thread_id: "77",  agent: escalations }         # one specific thread/forum-topic
      - { guild_id: "9001", agent: support, profile: acme } # a whole server/workspace

Routing Flow Diagram

Best Practices

Related