Skip to main content
The Channels API enables OpenFang agents to communicate through 40+ messaging platforms including Telegram, Discord, Slack, WhatsApp, Matrix, and more.

​
List Channels

Retrieve all configured channel adapters and their status. 
curl http://127.0.0.1:4200/api/channels
​
channels
array
{
  "channels": [
    {
      "name": "telegram",
      "enabled": true,
      "has_token": true,
      "display_name": "Telegram",
      "icon": "TG",
      "description": "Telegram Bot API — long-polling adapter",
      "category": "messaging",
      "difficulty": "Easy",
      "setup_time": "~2 min"
    },
    {
      "name": "discord",
      "enabled": true,
      "has_token": false,
      "display_name": "Discord",
      "icon": "DC",
      "description": "Discord Gateway bot adapter",
      "category": "messaging",
      "difficulty": "Easy",
      "setup_time": "~3 min"
    }
  ],
  "total": 2
}

​
Configure Channel

Add or update a channel configuration. 
curl -X POST http://127.0.0.1:4200/api/channels/{name}/configure \
  -H "Content-Type: application/json" \
  -d '{
    "bot_token_env": "TELEGRAM_BOT_TOKEN",
    "default_agent": "assistant",
    "allowed_users": ["123456", "789012"]
  }'
​
name
string
required
Channel adapter name (e.g., telegram, discord, slack)
​
bot_token_env
string
Environment variable name containing the bot token
​
default_agent
string
Default agent name to handle messages
​
allowed_users
array
Whitelist of user IDs (platform-specific)
​
allowed_channels
array
Whitelist of channel/room IDs (for Slack, Discord)
​
allowed_guilds
array
Whitelist of guild/server IDs (for Discord)
Configuration fields vary by channel adapter. See channel-specific documentation for full schemas.
{
  "status": "configured",
  "channel": "telegram"
}

​
Remove Channel

Remove a channel configuration. 
curl -X DELETE http://127.0.0.1:4200/api/channels/{name}/configure
​
name
string
required
Channel adapter name
{
  "status": "removed",
  "channel": "telegram"
}

​
Test Channel

Send a test message through a channel to verify configuration. 
curl -X POST http://127.0.0.1:4200/api/channels/{name}/test \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "123456",
    "message": "Test message from OpenFang"
  }'
​
name
string
required
Channel adapter name
​
recipient
string
required
Recipient ID (user ID, channel ID, etc.)
​
message
string
required
Test message text
{
  "status": "ok",
  "channel": "telegram",
  "message_id": "msg_123456"
}

​
Reload Channels

Reload all channel configurations from config.toml without restarting the daemon. 
curl -X POST http://127.0.0.1:4200/api/channels/reload

{
  "status": "reloaded",
  "channels_loaded": 5
}

​
WhatsApp QR Login

WhatsApp supports two modes: QR code scan (personal WhatsApp) and Business API (requires Meta developer account).

​
Start QR Login

Initiate WhatsApp QR code login flow. 
curl -X POST http://127.0.0.1:4200/api/channels/whatsapp/qr/start
​
session_id
string
QR session ID
​
qr_code
string
Base64-encoded QR code PNG image
​
expires_in
integer
QR code expiration time in seconds
{
  "session_id": "qr_abc123",
  "qr_code": "iVBORw0KGgoAAAANSUhEUgAA...",
  "expires_in": 60
}

​
Check QR Status

Poll for QR code scan completion. 
curl http://127.0.0.1:4200/api/channels/whatsapp/qr/status?session_id=qr_abc123
​
session_id
string
required
QR session ID
​
status
string
Status: pending, scanned, authenticated, expired, failed
​
phone_number
string
Authenticated phone number (when authenticated)
{
  "status": "pending"
}

​
Supported Channels

OpenFang supports 40+ channel adapters across 5 categories:

​
Messaging (12)

  • Telegram — Bot API with long-polling
  • Discord — Gateway bot adapter
  • Slack — Socket Mode + Events API
  • WhatsApp — Personal (QR) + Business API
  • Signal — signal-cli REST API
  • Matrix — Matrix/Element bot
  • LINE — LINE Messaging API
  • Viber — Viber Bot API
  • Messenger — Facebook Messenger
  • WeChat — WeChat Official Account
  • Kik — Kik Bot API
  • Threema — Threema Gateway

​
Team Collaboration (8)

  • Microsoft Teams — Bot Framework
  • Mattermost — Webhooks + API
  • Rocket.Chat — Real-time API
  • Zulip — Bot API
  • Google Chat — Chat API
  • Webex Teams — Webex Bot
  • Flock — Flock Bot API
  • Chanty — Chanty API

​
Email (3)

  • SMTP — Outbound email
  • IMAP — Inbound email polling
  • Gmail API — Gmail integration

​
Social (10)

  • Twitter/X — Twitter API v2
  • Reddit — Reddit API
  • Mastodon — Mastodon API
  • Bluesky — AT Protocol
  • LinkedIn — LinkedIn API
  • Instagram — Instagram Graph API
  • Snapchat — Snap Kit
  • TikTok — TikTok API
  • Pinterest — Pinterest API
  • Tumblr — Tumblr API

​
Voice/Video (4)

  • Twilio — SMS + Voice
  • Twitch — Twitch Chat IRC
  • YouTube Live — Live Chat API
  • Zoom — Zoom Chat Bot

​
Other (3)

  • IRC — Traditional IRC
  • XMPP/Jabber — XMPP protocol
  • SMS — Generic SMS gateway

​
Channel Configuration

Channels are configured in ~/.openfang/config.toml: 
[channels.telegram]
bot_token_env = "TELEGRAM_BOT_TOKEN"
default_agent = "assistant"
allowed_users = ["123456", "789012"]
poll_interval_secs = 1

[channels.discord]
bot_token_env = "DISCORD_BOT_TOKEN"
default_agent = "assistant"
allowed_guilds = ["123456789"]
intents = 37376  # MESSAGE_CONTENT + GUILD_MESSAGES

[channels.slack]
app_token_env = "SLACK_APP_TOKEN"
bot_token_env = "SLACK_BOT_TOKEN"
default_agent = "assistant"
allowed_channels = ["C01234", "C56789"]
After updating the config, reload channels: 
curl -X POST http://127.0.0.1:4200/api/channels/reload

​
Message Routing

When a message arrives from a channel:
  1. Extract sender identity — Platform-specific user ID
  2. Check agent bindings — Look for user-to-agent mapping
  3. Fall back to default — Use default_agent from config
  4. Send to agent — Forward message to resolved agent
  5. Stream response — Send agent’s reply back to channel

​
Agent Bindings

Map specific users to specific agents: 
curl -X POST http://127.0.0.1:4200/api/bindings \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "telegram",
    "user_id": "123456",
    "agent_name": "coder"
  }'
Now Telegram user 123456 will always talk to the coder agent.

​
Best Practices

Never hardcode bot tokens in config.toml. Use env vars:
[channels.telegram]
bot_token_env = "TELEGRAM_BOT_TOKEN"
Then set the env var:
export TELEGRAM_BOT_TOKEN="123456:ABC-DEF..."
openfang restart
Restrict channel access to known users:
[channels.telegram]
bot_token_env = "TELEGRAM_BOT_TOKEN"
allowed_users = ["123456", "789012"]
Messages from other users will be rejected.
Create specialized agents for each platform:
[channels.telegram]
default_agent = "telegram_assistant"

[channels.slack]
default_agent = "team_coordinator"
This allows platform-specific behavior and context.
Always test after configuring:
curl -X POST http://127.0.0.1:4200/api/channels/telegram/test \
  -d '{"recipient": "<your-user-id>", "message": "Test"}'
Verify you receive the test message on the platform.
Check logs for channel errors:
openfang logs --follow | grep "channel_bridge"
Or use the live log streaming endpoint:
curl http://127.0.0.1:4200/api/logs/stream

​
Next Steps

Agents API

Configure agents for channels

Agent Bindings

Map users to agents

Channel Setup

Platform-specific guides

Security

Secure channel configurations

Build docs developers (and LLMs) love

Get started for freeTalk to us