> ## 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 > Instance management, automations, access control, webhooks, and contact directory. # Management Commands Commands for managing instances, automations, access control, webhooks, and the contact directory. ## `omni instances` Manage channel connections. See [Instances concept page](/omni/concepts/instances) for detailed documentation. ```bash theme={"dark"} omni instances list # List all instances omni instances get # Get details omni instances create [options] # Create a new instance omni instances delete # Delete an instance omni instances status # Connection status omni instances whoami # Show phone/identity omni instances connect # Connect omni instances disconnect # Disconnect omni instances restart # Restart omni instances logout # Logout and clear session omni instances update [options] # Update settings ``` ### Updating Instance Settings `omni instances update ` 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 `. **Split delay** — controls the pause between chunks when an agent reply is auto-split on double newlines: | Flag | Description | | --------------------------- | -------------------------------------------------- | | `--split-delay-mode ` | `disabled`, `fixed`, or `randomized` | | `--split-delay-fixed ` | Fixed delay between chunks (use with mode `fixed`) | | `--split-delay-min ` | Lower bound (use with mode `randomized`) | | `--split-delay-max ` | Upper bound (use with mode `randomized`) | ```bash theme={"dark"} # 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 ```bash theme={"dark"} omni instances qr # Display QR code omni instances pair --phone +5511999999999 # Pairing code ``` ### Sync and Contacts ```bash theme={"dark"} omni instances sync # Start sync omni instances syncs # List sync jobs omni instances contacts # List contacts omni instances groups # List groups omni instances profile # Get user profile omni instances check # Check WhatsApp registration ``` ### WhatsApp Account Management Commands for managing the WhatsApp account associated with an instance. ```bash theme={"dark"} omni instances update-bio # Update profile bio/status omni instances block # Block a contact omni instances unblock # Unblock a contact omni instances blocklist # List blocked contacts omni instances update-picture [options] # Update profile picture omni instances remove-picture # Remove profile picture omni instances privacy # Fetch privacy settings omni instances reject-call [options] # Reject an incoming call ``` ```bash theme={"dark"} # 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. ```bash theme={"dark"} omni instances group-create [options] # Create a new group omni instances group-update-picture [options] # Update group picture omni instances group-invite # Get group invite link omni instances group-revoke-invite # Revoke and regenerate invite link omni instances group-join # Join a group via invite code ``` ```bash theme={"dark"} # 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. ```bash theme={"dark"} omni automations list # List all automations omni automations get # Get details omni automations create [options] # Create an automation omni automations update [options] # Update an automation omni automations delete # Delete omni automations enable # Enable omni automations disable # Disable omni automations test [options] # Test with mock event (dry run) omni automations execute [opts] # Execute with real event omni automations logs [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: ```text theme={"dark"} chat → instance → agent → (no config) ``` `enabled: false` at any level explicitly disables the sequence at that scope — broader scopes do **not** leak through. ```bash theme={"dark"} omni follow-up get # Read config at agents|instances|chats omni follow-up set # Write config (literal JSON, @path, or `-` for stdin) omni follow-up unset # Clear override so the next-broader scope applies ``` ### Config shape ```json theme={"dark"} { "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 ```bash theme={"dark"} # 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 '{ "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 @./follow-up.json # Disable for one chat without touching the agent/instance defaults omni follow-up set chats '{"enabled": false, "schedule": {"kind":"fixed","intervalsMinutes":[60]}, "maxFollowUps": 1, "promptTemplate": "x"}' # Remove the override and inherit again omni follow-up unset chats ``` 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. ```bash theme={"dark"} omni access list --instance # List rules omni access create [options] # Create a rule omni access delete # Delete a rule omni access mode [mode] # Get/set access mode omni access check [options] # Check if user has access omni access pending # List pending requests omni access approve # Approve pairing request omni access deny # Deny pairing request ``` *** ## `omni webhooks` Manage webhook event sources for custom integrations. ```bash theme={"dark"} omni webhooks list # List webhook sources omni webhooks get # Get details omni webhooks create [options] # Create a webhook source omni webhooks update [options] # Update omni webhooks delete # Delete omni webhooks trigger [options] # Trigger a custom event ``` *** ## `omni persons` Search and inspect contacts in the unified person directory. ```bash theme={"dark"} omni persons search # Search by name or phone omni persons get # Get full person profile omni persons presence # 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 --help` for the full flag table.