Skip to main content

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.

​
Instances

An instance is a connection to a messaging channel — a WhatsApp number, a Discord bot, a Telegram bot, or a Slack workspace. Each instance has its own identity, session state, and message history.

​
Supported Channels

ChannelAdapterConnection Method
WhatsApp (Baileys)whatsapp-baileysQR code or pairing code
WhatsApp (Cloud API)whatsapp-cloudMeta-issued access token
Gupshup (BSP)gupshupApp-name + API key + webhook
DiscorddiscordBot token (voice via DAVE E2EE)
TelegramtelegramBot API token
SlackslackOAuth / Bot token

​
Instance Lifecycle

created → connecting → connected → disconnected
                          ↓
                       restarting

​
Creating an Instance

omni instances create --channel whatsapp-baileys --name "Support Line"

​
Connecting (WhatsApp)

WhatsApp instances require pairing via QR code or pairing code: 
# QR code — displays in terminal, scan with phone
omni instances qr <instance-id>

# Pairing code — alternative for headless setups
omni instances pair <instance-id> --phone +5511999999999

​
Managing Connections

omni instances connect <id>      # Reconnect a disconnected instance
omni instances disconnect <id>   # Gracefully disconnect
omni instances restart <id>      # Restart the connection
omni instances logout <id>       # Logout and clear session data
omni instances status <id>       # Check connection status
omni instances whoami <id>       # Show phone number and identity

​
Sync Operations

Sync imports contacts, groups, and message history from the channel: 
# Start a sync
omni instances sync <id>

# Check sync job status
omni instances syncs <id>
omni instances syncs <id> <job-id>
For history backfill: 
omni resync --instance <id> --since 30d

​
Instance Management

For advanced instance operations including profile, privacy, and group management, see the management CLI reference. 
# List all instances
omni instances list

# Get instance details
omni instances get <id>

# Update instance settings
omni instances update <id> --name "New Name"

# Delete an instance
omni instances delete <id>

​
WhatsApp-Specific Features

# Contacts and groups
omni instances contacts <id>
omni instances groups <id>

# Profile management
omni instances update-bio <id> "New status message"
omni instances update-picture <id> --url https://example.com/avatar.jpg
omni instances remove-picture <id>

# Group management
omni instances group-create <id> --subject "Team Chat" --participants "+5511..." "+5511..."
omni instances group-invite <id> <group-jid>
omni instances group-revoke-invite <id> <group-jid>

# Privacy and blocking
omni instances privacy <id>
omni instances block <id> <contact-id>
omni instances unblock <id> <contact-id>
omni instances blocklist <id>

# Check if a number is on WhatsApp
omni instances check <id> +5511999999999
omni instances delete and omni instances logout both invalidate the channel session — delete removes the row and history, logout keeps the row but clears credentials. Neither is recoverable; re-pairing requires going through QR/pair flow again.
Run omni instances whoami <id> right after pairing to confirm the connected phone/identity matches what you expect — pairing a wrong number is the most common silent setup failure.

​
See also

Management CLI

Full omni instances reference + WhatsApp pairing, sync, group management.

AI agent integration

Bind agents to instances via providers and routes.

Routes

Filter which messages reach the agent on each instance.