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
--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
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>
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.
omni <command> --help for the full flag table.
