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]

Option	Description
`--instance <id>`	Instance ID
`--scope <scope>`	Filter by scope: `chat` or `user`
`--active`	Show 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]

Option	Description
`--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-stream`	Enable or disable streaming responses
`--prefix-sender` / `--no-prefix-sender`	Prefix messages with sender name
`--wait-media` / `--no-wait-media`	Wait for media processing before routing
`--send-media-path` / `--no-send-media-path`	Include file path in media text
`--gate` / `--no-gate`	Enable 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)
`--inactive`	Create 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]

Option	Description
`--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

`omni persons search`

Search the person directory.

omni persons search <query> [options]

Option	Description
`--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]

Option	Description
`--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>

Option	Description
`--reason <reason>`	Reason for merge

omni persons merge person-abc person-def --reason "Same WhatsApp user across two instances"

`omni persons link`

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

`omni persons unlink`

Remove a platform identity from its person record.

omni persons unlink [options] <identityId>

Option	Description
`--reason <reason>`	Reason for unlinking (default: `"Manual unlink"`)

omni persons unlink identity-abc --reason "Incorrectly linked"

Auth Commands

Save API credentials.

omni auth login [options]

Option	Description
`--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]

Option	Description
`--api-url <url>`	API base URL (default: `http://localhost:8882`)
`--rotate`	Generate 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]

Option	Description
`--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]

Option	Description
`--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]

Option	Description
`--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]

Option	Description
`--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.

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.

Getting Started

Core Concepts

CLI Reference

Architecture

Routes, Persons & Auth

Routes, Persons & Auth

Route Commands

`omni routes list`

`omni routes get`

`omni routes create`

`omni routes update`

`omni routes delete`

`omni routes test`

`omni routes metrics`

Person Commands

`omni persons search`

`omni persons get`

`omni persons presence`

`omni persons update`

`omni persons merge`

`omni persons link`

`omni persons unlink`

Auth Commands

`omni auth status`

`omni auth logout`

`omni auth recover`

API Key Commands

`omni keys create`

`omni keys list`

`omni keys get`

`omni keys update`

`omni keys revoke`

`omni keys delete`

See also

Routes (concept)

Auth & API keys

Webhooks

Instances

​Routes, Persons & Auth

​Route Commands

​omni routes list

​omni routes get

​omni routes create

​omni routes update

​omni routes delete

​omni routes test

​omni routes metrics

​Person Commands

​omni persons search

​omni persons get

​omni persons presence

​omni persons update

​omni persons merge

​omni persons link

​omni persons unlink

​Auth Commands

​omni auth login

​omni auth status

​omni auth logout

​omni auth recover

​API Key Commands

​omni keys create

​omni keys list

​omni keys get

​omni keys update

​omni keys revoke

​omni keys delete

​See also

Routes (concept)

Auth & API keys

Webhooks

Instances

Routes, Persons & Auth

Route Commands

`omni routes list`

`omni routes get`

`omni routes create`

`omni routes update`

`omni routes delete`

`omni routes test`

`omni routes metrics`

Person Commands

`omni persons search`

`omni persons get`

`omni persons presence`

`omni persons update`

`omni persons merge`

`omni persons link`

`omni persons unlink`

Auth Commands

`omni auth login`

`omni auth status`

`omni auth logout`

`omni auth recover`

API Key Commands

`omni keys create`

`omni keys list`

`omni keys get`

`omni keys update`

`omni keys revoke`

`omni keys delete`

See also