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

Channel	Adapter	Connection Method
WhatsApp (Baileys)	`whatsapp-baileys`	QR code or pairing code
WhatsApp (Cloud API)	`whatsapp-cloud`	Meta-issued access token
Gupshup (BSP)	`gupshup`	App-name + API key + webhook
Discord	`discord`	Bot token (voice via DAVE E2EE)
Telegram	`telegram`	Bot API token
Slack	`slack`	OAuth / Bot token

Instance Lifecycle

123created → connecting → connected → disconnected
                          ↓
                       restarting

Creating an Instance

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

Connecting (WhatsApp)

WhatsApp instances require pairing via QR code or pairing code:

12345# 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

123456omni 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:

123456# Start a sync
omni instances sync <id>

# Check sync job status
omni instances syncs <id>
omni instances syncs <id> <job-id>

For history backfill:

1omni resync --instance <id> --since 30d

Instance Management

For advanced instance operations including profile, privacy, and group management, see the management CLI reference.

1234567891011# 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

12345678910111213141516171819202122# 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.