Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.automagik.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
AI Agent Integration

Omni routes incoming messages to AI agents. You define providers (the AI backend), create agents (the entity that receives messages), and configure routes (which agent handles which conversations).

​
Concepts

ConceptWhat It Is
ProviderAn AI backend — Genie, Claude Code, A2A, Agno, webhook, etc.
AgentAn entity bound to a provider that processes messages
RouteA rule that sends messages from a specific instance/chat/user to an agent

​
Providers

Providers are the AI backends that power agents. 
# List providers
omni providers list

# Create a Genie provider
omni providers create --name "Genie" --schema genie

# Create a Claude Code provider
omni providers create --name "Claude" --schema claude-code

# Test provider health
omni providers test <provider-id>

# Interactive setup wizard
omni providers setup
Supported provider types: genie, claude-code, a2a, ag-ui, agno, openclaw, webhook.

​
Agents

Agents are the entities that receive and process messages. See the agents CLI reference for full management commands. 
# List all agents
omni agents list

# Create an agent
omni agents create --name "Support Bot" --provider <provider-id>

# Get agent details
omni agents get <agent-id>

# Delete an agent (soft-delete, sets inactive)
omni agents delete <agent-id>

​
Routes

Routes determine which agent handles messages from which source. Routes can be scoped to an instance, a specific chat, or a specific user. 
# List routes for an instance
omni routes list --instance <instance-id>

# Create a route — all messages from this instance go to this agent
omni routes create --instance <instance-id> --agent <agent-id>

# Create a per-chat route override
omni routes create --instance <instance-id> --chat <chat-id> --agent <agent-id>

# Create a per-user route override
omni routes create --instance <instance-id> --person <person-id> --agent <agent-id>

# Test route resolution
omni routes test --instance <instance-id> --chat <chat-id> --person <person-id>

# View route cache metrics
omni routes metrics

# Update or delete routes
omni routes update <route-id> --agent <new-agent-id>
omni routes delete <route-id>

​
Route Resolution Order

When a message arrives, Omni resolves the handler in this order:
  1. Per-user route — if a route exists for this specific person, use it
  2. Per-chat route — if a route exists for this specific chat, use it
  3. Per-instance route — fallback to the instance-level default agent

​
Reply Filters

Each instance can constrain which inbound messages reach the bound agent. The default is allow-all: when an instance has no reply filter set (agent_reply_filter = null), every message routed to the agent is dispatched. Switching to filtered mode lets you opt into specific triggers — DMs, @mentions, replies to the bot, or messages mentioning the bot’s name. 
# Default behaviour (no filter) — agent sees every message
omni instances update my-whatsapp --clear-reply-filter

# Constrain to DMs and @mentions only
omni instances update my-whatsapp \
  --reply-filter-mode filtered \
  --reply-on-dm \
  --reply-on-mention

# Match custom name patterns in group chats
omni instances update my-whatsapp \
  --reply-filter-mode filtered \
  --reply-on-name \
  --reply-name-patterns "support,help bot,assistant"
See omni instances update for every reply-filter flag.

​
API Keys

Manage API keys for authenticating with the Omni API: 
omni keys create --name "Production"
omni keys list
omni keys revoke <key-id>
Three concepts are easy to confuse on first read: a provider is reusable infrastructure (auth + base URL), an agent is a logical entity bound to one provider, and a route decides which agent handles a given conversation. You typically have a handful of providers, a few dozen agents, and routes per instance.
For routine deactivation prefer omni keys revoke over omni keys delete — revoked keys keep their audit trail and still appear in omni keys list, which makes incident review and rotation tracking much easier.

​
See also

Routes (concept)

Routing rules, priorities, and resolution order.

Instances (concept)

Per-channel configuration that scopes agent behaviour.

Agents (CLI)

omni agents, omni providers, omni routes, omni keys reference.

Providers (CLI)

Per-provider config schemas and setup wizards.