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

> Channel connections — WhatsApp, Discord, Telegram, Slack lifecycle, QR pairing, and sync.

# 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

```text theme={"dark"}
created → connecting → connected → disconnected
                          ↓
                       restarting
```

### Creating an Instance

```bash theme={"dark"}
omni instances create --channel whatsapp-baileys --name "Support Line"
```

### Connecting (WhatsApp)

WhatsApp instances require pairing via QR code or pairing code:

```bash theme={"dark"}
# 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

```bash theme={"dark"}
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:

```bash theme={"dark"}
# Start a sync
omni instances sync <id>

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

For history backfill:

```bash theme={"dark"}
omni resync --instance <id> --since 30d
```

## Instance Management

For advanced instance operations including profile, privacy, and group management, see the [management CLI reference](/omni/cli/management).

```bash theme={"dark"}
# 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

```bash theme={"dark"}
# 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
```

<Warning>
  `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.
</Warning>

<Tip>
  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.
</Tip>

## See also

<CardGroup cols={2}>
  <Card title="Management CLI" icon="terminal" href="/omni/cli/management">
    Full `omni instances` reference + WhatsApp pairing, sync, group management.
  </Card>

  <Card title="AI agent integration" icon="robot" href="/omni/concepts/agents">
    Bind agents to instances via providers and routes.
  </Card>

  <Card title="Routes" icon="diagram-project" href="/omni/concepts/routes">
    Filter which messages reach the agent on each instance.
  </Card>
</CardGroup>