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.

​
Routes, Persons & Auth

Three command groups for access and routing: omni routes controls which agent handles which chat, omni persons manages the contact directory, and omni auth/omni keys handle authentication and API key lifecycle.

​
Route Commands

Routes determine which AI agent handles messages for a specific chat or person.

​
omni routes list

List agent routes for an instance. 
omni routes list [options]
OptionDescription
--instance <id>Instance ID
--scope <scope>Filter by scope: chat or user
--activeShow only active routes

​
omni routes get

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

​
omni routes create

Create a new agent route. 
omni routes create [options]
OptionDescription
--instance <id>Instance ID
--scope <scope>Route scope: chat or user
--chat <chat-id>Chat UUID (required when scope=chat)
--person <person-id>Person UUID (required when scope=user)
--agent <agent-id>Agent UUID
--timeout <seconds>Agent timeout in seconds
--stream / --no-streamEnable or disable streaming responses
--prefix-sender / --no-prefix-senderPrefix messages with sender name
--wait-media / --no-wait-mediaWait for media processing before routing
--send-media-path / --no-send-media-pathInclude file path in media text
--gate / --no-gateEnable or disable LLM response gate
--gate-model <model>Response gate model
--gate-prompt <prompt>Response gate prompt
--reply-filter-mode <mode>Reply filter: all or filtered
--label <label>Human-readable label
--priority <number>Priority (higher = higher priority, default: 0)
--inactiveCreate as inactive
# Route a chat to an agent
omni routes create \
  --instance <id> \
  --scope chat \
  --chat <chat-uuid> \
  --agent <agent-uuid> \
  --label "Support Bot"

# Route all messages from a person to an agent
omni routes create \
  --instance <id> \
  --scope user \
  --person <person-uuid> \
  --agent <agent-uuid> \
  --gate \
  --gate-model "claude-sonnet-4-20250514"

# High-priority route with streaming
omni routes create \
  --instance <id> \
  --scope chat \
  --chat <chat-uuid> \
  --agent <agent-uuid> \
  --stream \
  --priority 10

​
omni routes update

Update an existing route. Accepts the same options as create. 
omni routes update <route-id> [options]

​
omni routes delete

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

​
omni routes test

Test which route would resolve for a given instance, chat, and/or person. 
omni routes test [options]
OptionDescription
--instance <id>Instance ID
--chat <chat-id>Chat UUID to test
--person <person-id>Person UUID to test
omni routes test --instance <id> --chat <chat-uuid>

​
omni routes metrics

View route cache metrics. 
omni routes metrics

​
Person Commands

Search the person directory. 
omni persons search <query> [options]
OptionDescription
--limit <n>Limit results (default: 20)
omni persons search "João" --limit 10

​
omni persons get

Get full person details. 
omni persons get <id>

​
omni persons presence

Get person presence and activity info. 
omni persons presence <id>

​
omni persons update

Update person fields. 
omni persons update <id> [options]
OptionDescription
--name <name>Display name
--phone <phone>Primary phone (E.164 format)
--email <email>Primary email
--avatar <url>Avatar URL
--metadata <json>Metadata as JSON string
omni persons update abc123 --name "João Silva" --email "joao@example.com"

​
omni persons merge

Merge two person records into one. The source person is deleted and all identities transfer to the target. Use this to deduplicate contacts that represent the same person across different instances. 
omni persons merge [options] <source> <target>
OptionDescription
--reason <reason>Reason for merge
omni persons merge person-abc person-def --reason "Same WhatsApp user across two instances"
Link two platform identities to the same person. Useful when the same person has accounts on different channels (WhatsApp, Telegram, etc.) that Omni has not auto-matched. 
omni persons link <identityA> <identityB>

omni persons link identity-whatsapp-123 identity-telegram-456
Remove a platform identity from its person record. 
omni persons unlink [options] <identityId>
OptionDescription
--reason <reason>Reason for unlinking (default: "Manual unlink")
omni persons unlink identity-abc --reason "Incorrectly linked"

​
Auth Commands

​
omni auth login

Save API credentials. 
omni auth login [options]
OptionDescription
--api-key <key>API key for authentication
--api-url <url>API base URL (default: http://localhost:8882)

​
omni auth status

Show current authentication status. 
omni auth status

​
omni auth logout

Clear stored credentials. 
omni auth logout

​
omni auth recover

Recover API key when auth is invalid. Requires local PM2 access. 
omni auth recover [options]
OptionDescription
--api-url <url>API base URL (default: http://localhost:8882)
--rotateGenerate a new key instead of recovering the existing one

​
API Key Commands

​
omni keys create

Create a new API key with scoped permissions. 
omni keys create [options]
OptionDescription
--name <name>Key name
--scopes <scopes>Comma-separated scopes (e.g., messages:read,instances:write)
--instances <ids>Comma-separated instance IDs to restrict access
--description <desc>Key description
--rate-limit <n>Rate limit (requests/minute)
--expires <date>Expiration date (ISO 8601)
# Full-access key
omni keys create --name "admin" --scopes "*"

# Scoped read-only key
omni keys create \
  --name "monitoring" \
  --scopes "messages:read,events:read" \
  --rate-limit 100

# Instance-restricted key with expiry
omni keys create \
  --name "temp-access" \
  --instances <id1>,<id2> \
  --expires 2025-12-31T23:59:59Z

​
omni keys list

List API keys. 
omni keys list [options]
OptionDescription
--status <status>Filter by status: active, revoked, expired
--limit <n>Max results

​
omni keys get

Get API key details. 
omni keys get <id>

​
omni keys update

Update an API key. 
omni keys update <id> [options]
OptionDescription
--name <name>New name
--description <desc>New description
--scopes <scopes>New scopes (comma-separated)
--instances <ids>New instance IDs (empty string to unrestrict)
--rate-limit <n>New rate limit
--expires <date>New expiration (empty string to clear)

​
omni keys revoke

Revoke an API key. 
omni keys revoke <id> [options]
OptionDescription
--reason <reason>Reason for revocation

​
omni keys delete

Permanently delete an API key. 
omni keys delete <id>
omni keys delete is irreversible — there is no soft-delete or undo. Prefer omni keys revoke <id> for routine deactivation; revoked keys retain their audit trail and can still appear in omni keys list.
omni persons merge and omni persons link rewrite the canonical person identity. Downstream automations keyed on the merged-away personId will start receiving events under the surviving ID — coordinate with anyone who built dashboards or alerts on those IDs before merging.
Bulk-restrict a key to specific instances by passing a comma list: omni keys update <id> --instances "wa-prod,wa-staging". Pass an empty string --instances "" to remove the restriction.

​
See also

Routes (concept)

Routing rules, priorities, and resolution order.

Auth & API keys

omni keys quick reference and agent-side key usage.

Webhooks

Inbound auth surfaces for custom integrations.

Instances

Per-instance access and identity model.