Skip to main content

​
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 <routeId>

​
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 <chatId>Chat UUID (required when scope=chat)
--person <personId>Person UUID (required when scope=user)
--agent <agentId>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 <routeId> [options]

​
omni routes delete

Delete a route. 
omni routes delete <routeId>

​
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 <chatId>Chat UUID to test
--person <personId>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>

​
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>