Guide
Channels Guide
Connect Omni to 21 messaging platforms. Route incoming messages to extensions with bindings.
Overview
Channels are messaging platform integrations that let your Omni agent send and receive messages through external services. Each channel runs as an independent plugin with its own connection lifecycle, authentication, and message format.
Key concepts:
Supported Channels
Omni supports 21 messaging platforms. All channels are free to use — no premium tiers or paid APIs required.
Connecting a Channel
Channels can be connected through the UI or pre-configured in omni.toml.
Via the UI
Open Settings → Channels
Click Add Instance and select a channel type
Enter an instance ID (e.g., "production") and optional display name
Enter authentication credentials (bot token, API key, etc.)
Click Connect — the channel status indicator turns green when ready
Via Config File
[channels.instances."discord:production"]
channel_type = "discord"
display_name = "Main Server"
auto_connect = true
# Credentials are provided at connect time, not stored in config
Connection Lifecycle
Disconnected
No active connection
Connecting
Establishing connection
Connected
Ready to send/receive
Reconnecting
Recovering from a drop
Error
Connection failed
Multi-Instance Support
You can run multiple instances of the same channel type simultaneously. Each instance has its own credentials, connection state, and message stream. Instances are identified by compound keys.
# Format: {channel_type}:{instance_id}
"discord:production" # Discord, production instance
"discord:staging" # Discord, staging instance
"telegram:alerts" # Telegram, alerts bot
"telegram:support" # Telegram, support bot
# Bare type defaults to "default" instance:
"discord" → "discord:default"
Use cases: separate bots for production and development, multiple Telegram bots for different teams, or different Slack workspaces connected at once.
Message Routing & Bindings
Channel bindings route incoming messages from a channel instance to a specific extension. Without a binding, messages from a channel are not forwarded to any extension.
Binding Fields
Resolution Order
When multiple bindings match an incoming message, Omni resolves the conflict using:
Priority — higher priority bindings are preferred
Specificity — more specific glob patterns (fewer wildcards) win over broader ones
First match — if still tied, the first registered binding wins
# Route all Discord support channels to the support bot
[[channels.bindings]]
channel_instance = "discord:production"
extension_id = "com.example.support-bot"
group_filter = "support-*"
priority = 100
# Catch-all for everything else on Discord
[[channels.bindings]]
channel_instance = "discord:production"
extension_id = "com.example.general-bot"
peer_filter = "*"
priority = 10
Channel Features
Each channel reports which features it supports. Extensions can query these features to adapt their behavior.
Direct Messages
1-on-1 conversations
Group Messages
Multi-user channels and rooms
Media Attachments
Images, files, and other media
Reactions
Emoji reactions on messages
Read Receipts
Delivery and read confirmations
Typing Indicators
Show when someone is typing
Authentication Methods
Channels use different authentication flows depending on the platform.
Bot Token
Discord, Telegram, Slack, Mattermost, Synology Chat
Create a bot on the platform's developer portal, copy the token, and paste it into Omni. The token is stored securely and used for all API calls.
QR Code Pairing
WhatsApp Web, Signal
Omni displays a QR code in the UI. Scan it with your phone's app to link the session. No bot account needed — messages appear as coming from your personal account.
OAuth / API Key
Twitter/X, LINE, Google Chat, Feishu, Zalo
Register an application on the platform's developer console, obtain API keys or OAuth credentials, and enter them in Omni.
Server URL + Password
BlueBubbles, iMessage, Nextcloud Talk
Point Omni to a self-hosted server (e.g., BlueBubbles on a Mac) with its URL and password.
Troubleshooting
Channel stuck on "Connecting"
Check your credentials and internet connection. For bot-token channels, verify the token hasn't been revoked. For QR code channels, try disconnecting and re-scanning.
Messages not arriving
Ensure a binding exists for the channel instance. Without a binding, incoming messages are received but not routed to any extension. Check Settings → Channels → Bindings.
"Permission denied" when sending
The extension needs the channel.send capability. Check the extension's manifest or grant the permission when prompted.
WhatsApp Web disconnects frequently
WhatsApp Web sessions can expire if the phone loses internet or the app is force-closed. Keep the phone connected and the WhatsApp app running in the background.