Documentation Index
Fetch the complete documentation index at: https://docs.automagik.dev/llms.txt
Use this file to discover all available pages before exploring further.
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.
