Management Commands

Commands for managing instances, automations, access control, webhooks, and the contact directory.

`omni instances`

Manage channel connections. See Instances concept page for detailed documentation.

omni instances list                       # List all instances
omni instances get <id>                   # Get details
omni instances create [options]           # Create a new instance
omni instances delete <id>               # Delete an instance
omni instances status <id>               # Connection status
omni instances whoami <id>               # Show phone/identity
omni instances connect <id>              # Connect
omni instances disconnect <id>           # Disconnect
omni instances restart <id>              # Restart
omni instances logout <id>               # Logout and clear session
omni instances update <id> [options]     # Update settings

Updating Instance Settings

omni instances update <id> exposes every API field. Common groups: Agent binding — --agent-fk-id, --agent-provider, --agent, --agent-type, --agent-timeout, --agent-stream-mode / --no-agent-stream-mode, --agent-session-strategy. Reply filter — --reply-filter-mode all|filtered, plus --reply-on-dm, --reply-on-mention, --reply-on-reply, --reply-on-name, and --reply-name-patterns. Use --clear-reply-filter to remove the filter entirely (null = allow all messages through). Message timing — --debounce-mode, --debounce-min, --debounce-max, --debounce-restart-on-typing, and --debounce-group <ms>. Split delay — controls the pause between chunks when an agent reply is auto-split on double newlines:

Flag	Description
`--split-delay-mode <mode>`	`disabled`, `fixed`, or `randomized`
`--split-delay-fixed <ms>`	Fixed delay between chunks (use with mode `fixed`)
`--split-delay-min <ms>`	Lower bound (use with mode `randomized`)
`--split-delay-max <ms>`	Upper bound (use with mode `randomized`)

# Humanise multi-chunk replies with a 600–1200 ms randomised gap
omni instances update my-whatsapp \
  --enable-auto-split \
  --split-delay-mode randomized \
  --split-delay-min 600 \
  --split-delay-max 1200

# Disable split delay entirely (back-to-back chunks)
omni instances update my-whatsapp --split-delay-mode disabled

Other common flags — --access-mode, --reaction-ack, --ack-timeout, --tts-voice, --tts-model, --token, --profile-name. Run omni instances update --help for the full list.

WhatsApp Pairing

omni instances qr <id>                              # Display QR code
omni instances pair <id> --phone +5511999999999     # Pairing code

Sync and Contacts

omni instances sync <id>              # Start sync
omni instances syncs <id>             # List sync jobs
omni instances contacts <id>          # List contacts
omni instances groups <id>            # List groups
omni instances profile <id> <user-id>  # Get user profile
omni instances check <id> <phone>     # Check WhatsApp registration

WhatsApp Account Management

Commands for managing the WhatsApp account associated with an instance.

omni instances update-bio <id> <status>             # Update profile bio/status
omni instances block <id> <contactId>                # Block a contact
omni instances unblock <id> <contactId>              # Unblock a contact
omni instances blocklist <id>                        # List blocked contacts
omni instances update-picture <id> [options]         # Update profile picture
omni instances remove-picture <id>                   # Remove profile picture
omni instances privacy <id>                          # Fetch privacy settings
omni instances reject-call <id> [options]            # Reject an incoming call

# Update your WhatsApp bio
omni instances update-bio wa-main "Support Bot — online 24/7"

# Block a spam contact
omni instances block wa-main 5511999999999@s.whatsapp.net

# Check who's blocked
omni instances blocklist wa-main

# Update profile picture from file
omni instances update-picture wa-main --file avatar.png

# View privacy settings
omni instances privacy wa-main

WhatsApp Group Management

Commands for creating and managing WhatsApp groups.

omni instances group-create <id> [options]           # Create a new group
omni instances group-update-picture <id> [options]   # Update group picture
omni instances group-invite <id> <groupJid>          # Get group invite link
omni instances group-revoke-invite <id> <groupJid>   # Revoke and regenerate invite link
omni instances group-join <id> <code>                # Join a group via invite code

# Create a new WhatsApp group
omni instances group-create wa-main --name "Project Team" --participants 5511999999999@s.whatsapp.net

# Get an invite link for a group
omni instances group-invite wa-main 120363123456789@g.us

# Revoke the current invite link and generate a new one
omni instances group-revoke-invite wa-main 120363123456789@g.us

# Join a group via invite code
omni instances group-join wa-main AbCdEfGh

`omni automations`

Manage event-driven automations that trigger on message events.

omni automations list                   # List all automations
omni automations get <id>               # Get details
omni automations create [options]       # Create an automation
omni automations update <id> [options]  # Update an automation
omni automations delete <id>           # Delete
omni automations enable <id>           # Enable
omni automations disable <id>          # Disable
omni automations test <id> [options]   # Test with mock event (dry run)
omni automations execute <id> [opts]   # Execute with real event
omni automations logs <id> [options]   # View execution logs

`omni follow-up`

Configure the idle-chat follow-up sequence — when a customer goes quiet after an agent reply, Omni can fire a configurable cadence of nudges and stop on inbound, handoff, archive, or window expiry. Config is layered with closest scope wins at runtime:

chat  →  instance  →  agent  →  (no config)

enabled: false at any level explicitly disables the sequence at that scope — broader scopes do not leak through.

omni follow-up get <scope> <id>          # Read config at agents|instances|chats
omni follow-up set <scope> <id> <json>   # Write config (literal JSON, @path, or `-` for stdin)
omni follow-up unset <scope> <id>        # Clear override so the next-broader scope applies

Config shape

{
  "enabled": true,
  "schedule": {
    "kind": "fixed",
    "intervalsMinutes": [30, 120, 1440]
  },
  "maxFollowUps": 3,
  "promptTemplate": "Customer has been idle for {{minutes}} min. Send a friendly nudge.",
  "stopOutsideMessagingWindow": true,
  "showTypingIndicator": true
}

Field	Description
`enabled`	Master switch at this scope. `false` short-circuits broader scopes.
`schedule.kind`	`fixed` (cycle through `intervalsMinutes`) or `exponential` (`initialMinutes`, `factor`, `maxMinutes`).
`maxFollowUps`	Hard cap on follow-ups fired per sequence (1–50).
`promptTemplate`	Synthetic prompt sent to the agent. Placeholders: `{{minutes}}`, `{{sequenceIndex}}`, `{{chatName}}`, `{{syntheticPrompt}}`.
`stopOutsideMessagingWindow`	On WhatsApp BSP/Cloud, disarm when the last inbound is older than 24 h. Default `true`.
`showTypingIndicator`	Emit a 2–3 s typing/presence indicator before the follow-up on channels that support it. Default `true`.

Examples

# Apply a default sequence to every chat on an instance
omni follow-up set instances my-whatsapp '{
  "enabled": true,
  "schedule": { "kind": "fixed", "intervalsMinutes": [30, 120] },
  "maxFollowUps": 2,
  "promptTemplate": "Friendly nudge — customer idle {{minutes}}m."
}'

# Override a single chat with an exponential schedule
omni follow-up set chats <chat-id> '{
  "enabled": true,
  "schedule": { "kind": "exponential", "initialMinutes": 15, "factor": 2, "maxMinutes": 720 },
  "maxFollowUps": 5,
  "promptTemplate": "Idle nudge #{{sequenceIndex}} for {{chatName}}"
}'

# Read from a file
omni follow-up set agents <agent-id> @./follow-up.json

# Disable for one chat without touching the agent/instance defaults
omni follow-up set chats <chat-id> '{"enabled": false, "schedule": {"kind":"fixed","intervalsMinutes":[60]}, "maxFollowUps": 1, "promptTemplate": "x"}'

# Remove the override and inherit again
omni follow-up unset chats <chat-id>

A sequence is automatically disarmed when any of these happen: customer replies, chat is handed off, chat is archived/muted, the WhatsApp 24 h window expires, the agent errors, an outbound send fails, the user clears the agent session, or the configured maxFollowUps is reached.

`omni access`

Manage access control rules — allow/deny lists for instances.

omni access list --instance <id>               # List rules
omni access create [options]                   # Create a rule
omni access delete <id>                        # Delete a rule
omni access mode <instance-id> [mode]          # Get/set access mode
omni access check [options]                    # Check if user has access
omni access pending <instance-id>              # List pending requests
omni access approve <instance-id> <req-id>     # Approve pairing request
omni access deny <instance-id> <req-id>        # Deny pairing request

`omni webhooks`

Manage webhook event sources for custom integrations.

omni webhooks list                       # List webhook sources
omni webhooks get <id>                   # Get details
omni webhooks create [options]           # Create a webhook source
omni webhooks update <id> [options]      # Update
omni webhooks delete <id>               # Delete
omni webhooks trigger [options]          # Trigger a custom event

`omni persons`

Search and inspect contacts in the unified person directory.

omni persons search <query>     # Search by name or phone
omni persons get <id>           # Get full person profile
omni persons presence <id>      # Check online presence and activity

Server lifecycle

These commands manage the embedded Omni server itself rather than its conversation state. Use them when bringing a host online, recovering from a crash, or upgrading.

Command	Description
`omni install`	Bootstrap the server (non-interactive, reinstall-safe). Flags: `--port` (API port, default `8882`), `--database-url` (external PostgreSQL; defaults to embedded pgserve).
`omni start`	Start the server (idempotent — no-op if already running).
`omni stop`	Stop the server gracefully.
`omni restart`	Stop, then start. Use after env changes that need a fresh process.
`omni resync`	Re-pull external state (channels, contacts) without bouncing the process.
`omni status`	Show API health and connection info.
`omni doctor [--fix]`	Diagnose env drift, stale keys, version mismatch. `--fix` repairs WARN/FAIL checks in-place; never touches `~/.omni/data/pgserve`.
`omni update [-y] [--no-restart]`	Update `@automagik/omni` to the latest version. By default restarts services that were already running; `--no-restart` updates the CLI only.

Run omni doctor after every reinstall and before opening a support ticket — it surfaces misconfigured env vars, dangling keys, and version skew between CLI and server in one pass.

Run omni <command> --help for the full flag table.

Getting Started

Core Concepts

CLI Reference

Architecture

Management

Management Commands

`omni instances`

Updating Instance Settings

WhatsApp Pairing

Sync and Contacts

WhatsApp Account Management

WhatsApp Group Management

`omni automations`

`omni follow-up`

Config shape

Examples

`omni access`

`omni webhooks`

`omni persons`

Server lifecycle

​Management Commands

​omni instances

​Updating Instance Settings

​WhatsApp Pairing

​Sync and Contacts

​WhatsApp Account Management

​WhatsApp Group Management

​omni automations

​omni follow-up

​Config shape

​Examples

​omni access

​omni webhooks

​omni persons

​Server lifecycle

Management Commands

`omni instances`

Updating Instance Settings

WhatsApp Pairing

Sync and Contacts

WhatsApp Account Management

WhatsApp Group Management

`omni automations`

`omni follow-up`

Config shape

Examples

`omni access`

`omni webhooks`

`omni persons`

Server lifecycle