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.

1omni 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.

1omni routes get <route-id>

`omni routes create`

Create a new agent route.

1omni 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

12345678910111213141516171819202122232425# 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.

1omni routes update <route-id> [options]

`omni routes delete`

Delete a route.

1omni routes delete <route-id>

`omni routes test`

Test which route would resolve for a given instance, chat, and/or person.

1omni routes test [options]

Option	Description
`--instance <id>`	Instance ID
`--chat <chat-id>`	Chat UUID to test
`--person <person-id>`	Person UUID to test

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

`omni routes metrics`

View route cache metrics.

1omni routes metrics

Person Commands

`omni persons search`

Search the person directory.

1omni persons search <query> [options]

Option	Description
`--limit <n>`	Limit results (default: 20)

1omni persons search "João" --limit 10

`omni persons get`

Get full person details.

1omni persons get <id>

`omni persons presence`

Get person presence and activity info.

1omni persons presence <id>

`omni persons update`

Update person fields.

1omni 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

1omni 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.

1omni persons merge [options] <source> <target>

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

1omni 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.

1omni persons link <identityA> <identityB>

1omni persons link identity-whatsapp-123 identity-telegram-456

`omni persons unlink`

Remove a platform identity from its person record.

1omni persons unlink [options] <identityId>

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

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

Auth Commands

Save API credentials.

1omni 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.

1omni auth status

`omni auth logout`

Clear stored credentials.

1omni auth logout

`omni auth recover`

Recover API key when auth is invalid. Requires local PM2 access.

1omni 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.

1omni 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)

1234567891011121314# 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.

1omni keys list [options]

Option	Description
`--status <status>`	Filter by status: `active`, `revoked`, `expired`
`--limit <n>`	Max results

`omni keys get`

Get API key details.

1omni keys get <id>

`omni keys update`

Update an API key.

1omni 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.

1omni keys revoke <id> [options]

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

`omni keys delete`

Permanently delete an API key.

1omni 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, 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