Skip to main content

​
Overview

An instance is the central configuration entity in Ravi. Each instance represents a connected channel account (WhatsApp, Telegram, Discord, Matrix) with its own agent, access policies, and routing rules. Instances are stored in SQLite and managed entirely through the CLI.

​
Creating an Instance

Options:
  • --channel — Channel type: whatsapp, matrix, telegram, discord (default: whatsapp)
  • --agent — Default agent for this instance
  • --dm-policy — DM access policy (default: open)
  • --group-policy — Group access policy (default: open)
If the specified agent does not exist, the command will fail. Create the agent first with ravi agents create.

​
Connecting to a Channel

This creates the instance in omni (if needed), then waits for a QR code to pair WhatsApp. Once scanned, the instance is connected and begins receiving messages. You can also specify an agent during connection:
If the agent does not exist, it will be auto-created with a working directory at ~/ravi/<agentId>.

​
Check Status

Shows the connection state, profile name, channel, agent, and policies.

​
Disconnect

​
Access Policies

Policies control who can interact with the bot on a given instance. There are two independent policies: one for DMs and one for groups.

​
DM Policy

​
Group Policy

​
Setting Policies

​
Pending Contacts

When dmPolicy=pairing or groupPolicy=allowlist, unknown contacts and groups that send messages are placed in a pending queue instead of being rejected.

​
List Pending

Shows the phone/ID, type (DM or group), and name for each pending entry.

​
Approve

Approving a contact allows it and removes it from the pending list. The contact can now message the bot.

​
Reject

Rejecting removes the entry from the pending list without allowing it.

​
Per-Instance Routes

Routes define which agent handles messages from specific contacts, groups, or phone prefixes within an instance. Routes also support policy overrides and priority ordering.

​
Route Patterns

​
Adding Routes

Options:
  • --priority <n> — Higher priority routes are matched first (default: 0)
  • --policy <policy> — Override the instance policy for this route: open, pairing, closed, allowlist
  • --session <name> — Force a specific session name
  • --dm-scope <scope> — Override DM scope for this route
  • --channel <channel> — Limit route to a specific channel (omit for all channels)
When a route is added, any conflicting sessions (same pattern, different agent) are automatically cleaned up.

​
Managing Routes

Settable route properties: agent, priority, dmScope, session, policy, channel.

​
Agent Resolution Order

When a message arrives, Ravi resolves which agent handles it using this priority:
  1. Route match — The highest-priority route whose pattern matches the sender (scoped to the instance)
  2. Instance agent — The default agent configured on the instance (ravi instances set main agent <id>)
  3. Default agent — The global default agent from settings
If no agent can be resolved, the message is dropped.

​
DM Scope

DM scope controls how sessions are grouped for direct messages. It can be set at the instance level or overridden per route.

​
Active vs Sentinel Mode

Agent mode is configured at the agent level, but it directly affects how instances behave:
  • Active mode — The agent responds to messages automatically. This is the default.
  • Sentinel mode — The agent observes messages silently without auto-replying. Useful for monitoring accounts where the agent only acts when explicitly instructed.
A sentinel-mode agent will still receive and process messages (including tool use), but it will not send unsolicited responses back to the channel.

​
Instance Lifecycle

Instances follow a lifecycle that supports recovery:
  1. Create — ravi instances create registers the instance locally
  2. Connect — ravi instances connect creates the omni instance and initiates pairing
  3. Active — Messages flow through the instance, routed to agents
  4. Disconnect — ravi instances disconnect disconnects from the channel
  5. Delete (soft) — ravi instances delete marks the instance as deleted but keeps the data
  6. Restore — ravi instances restore recovers a soft-deleted instance
Routes also support soft-delete and restore.

​
Configurable Properties

Use - or null as the value to clear a property.

​
Multi-Account Setup

Run multiple channel accounts, each routed to a different agent:

​
Example: Public Bot

Accept all messages, no restrictions:

​
Example: Controlled Access

Only pre-approved contacts and allowlisted groups:
New senders appear in the pending list for review: