Routes

Routes are rules that determine which AI agent handles incoming messages. Omni supports hierarchical routing with per-instance defaults and per-chat/per-user overrides.

How Routing Works

When a message arrives on a channel instance, Omni evaluates routes in this order:

1Message arrives → Check per-user route → Check per-chat route → Check per-instance route → No agent (unrouted)

The first matching route wins. This lets you set a default agent for an instance while overriding specific conversations or users.

Creating Routes

Instance-Level Default

Route all messages from an instance to a single agent:

1omni routes create --instance <instance-id> --agent <agent-id>

Per-Chat Override

Route a specific conversation to a different agent:

1omni routes create --instance <instance-id> --chat <chat-id> --agent <agent-id>

Per-User Override

Route all messages from a specific person to a dedicated agent:

1omni routes create --instance <instance-id> --person <person-id> --agent <agent-id>

Testing Routes

Before going live, test how Omni would resolve a route:

1omni routes test --instance <instance-id> --chat <chat-id> --person <person-id>

This shows which agent would handle the message and why.

Managing Routes

For full route, person, and auth management commands, see the routes CLI reference.

1234567891011121314# List routes for an instance
omni routes list --instance <instance-id>

# Get route details
omni routes get <route-id>

# Update a route's target agent
omni routes update <route-id> --agent <new-agent-id>

# Delete a route
omni routes delete <route-id>

# View route cache metrics
omni routes metrics

Common Patterns

Default Agent + VIP Override

12345# Default: all messages go to support bot
omni routes create --instance $INST --agent $SUPPORT_BOT

# Override: VIP customer gets a dedicated agent
omni routes create --instance $INST --person $VIP_ID --agent $VIP_AGENT

Channel-Specific Agents

12345# WhatsApp instance → Portuguese-speaking agent
omni routes create --instance $WA_INST --agent $PT_AGENT

# Discord instance → English-speaking agent
omni routes create --instance $DC_INST --agent $EN_AGENT

Route resolution is per-message, evaluated by omni routes test exactly the same way the dispatcher evaluates it at runtime. Use omni routes test --instance <id> --chat <id> --person <id> before going live to confirm a route override resolves to the agent you expect.

Routes are cached. Use omni routes metrics to inspect cache hit rates — if they're low after a config change, the cache may be cold; if they're high but you're seeing the wrong agent, you may have a stale cache and need a process restart.