Channels API - OpenFang

Overview

Channels enable agents to interact with external platforms like messaging apps, social media, and notification services. OpenFang supports 40 adapters out of the box.

Channel Categories

Messaging (12)

Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Email, LINE, Viber, Messenger, Threema, Keybase

Social (5)

Reddit, Mastodon, Bluesky, LinkedIn, Nostr

Enterprise (10)

Teams, Mattermost, Google Chat, Webex, Feishu, DingTalk, Pumble, Flock, Twist, Zulip

Developer (9)

IRC, XMPP, Gitter, Discourse, Revolt, Guilded, Nextcloud, Rocket.Chat, Twitch

Notifications (4)

ntfy, Gotify, Webhook, Mumble

List Channels

Get all available channel adapters and their configuration status:

GET /api/channels

curl http://127.0.0.1:4200/api/channels

[
  {
    "name": "telegram",
    "display_name": "Telegram",
    "icon": "TG",
    "description": "Telegram Bot API — long-polling adapter",
    "category": "messaging",
    "difficulty": "Easy",
    "setup_time": "~2 min",
    "quick_setup": "Paste your bot token from @BotFather",
    "setup_type": "form",
    "configured": true,
    "active": true,
    "fields": [
      {
        "key": "bot_token_env",
        "label": "Bot Token",
        "type": "secret",
        "env_var": "TELEGRAM_BOT_TOKEN",
        "required": true,
        "has_value": true,
        "placeholder": "123456:ABC-DEF...",
        "advanced": false
      }
    ],
    "setup_steps": [
      "Open @BotFather on Telegram",
      "Send /newbot and follow the prompts",
      "Paste the token below"
    ],
    "config_template": "[channels.telegram]\nbot_token_env = \"TELEGRAM_BOT_TOKEN\""
  }
]

Configure Channel

Add or update a channel configuration:

POST /api/channels/{name}/configure

curl -X POST http://127.0.0.1:4200/api/channels/telegram/configure \
  -H "Content-Type: application/json" \
  -d '{
    "bot_token_env": "TELEGRAM_BOT_TOKEN",
    "default_agent": "assistant",
    "poll_interval_secs": 1
  }'

Common Fields

default_agent

string

Default agent to route messages to (by name)

allowed_users

array

Whitelist of user IDs (platform-specific)

allowed_channels

array

Whitelist of channel/room IDs

{
  "status": "configured",
  "channel": "telegram"
}

Remove Channel

Delete a channel configuration:

DELETE /api/channels/{name}/configure

curl -X DELETE http://127.0.0.1:4200/api/channels/telegram/configure

{
  "status": "removed",
  "channel": "telegram"
}

Test Channel

Verify a channel configuration by sending a test message:

POST /api/channels/{name}/test

curl -X POST http://127.0.0.1:4200/api/channels/telegram/test \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hello from OpenFang!"
  }'

{
  "status": "success",
  "message": "Test message sent"
}

Reload Channels

Hot-reload channel configuration without restarting:

POST /api/channels/reload

curl -X POST http://127.0.0.1:4200/api/channels/reload

{
  "status": "reloaded",
  "channels_active": 3
}

WhatsApp supports QR code login for personal accounts (no Business API needed).

Start QR Session

POST /api/channels/whatsapp/qr/start

curl -X POST http://127.0.0.1:4200/api/channels/whatsapp/qr/start

{
  "session_id": "qr-abc123",
  "status": "waiting_for_scan"
}

Get QR Status

Poll for QR code and connection status:

GET /api/channels/whatsapp/qr/status

curl http://127.0.0.1:4200/api/channels/whatsapp/qr/status?session_id=qr-abc123

{
  "status": "waiting_for_scan",
  "qr_code": "data:image/png;base64,...",
  "expires_at": "2025-03-06T12:05:00Z"
}

Once scanned:

{
  "status": "connected",
  "phone_number": "+1234567890"
}

Messaging Channels

Setup: Create a bot with @BotFather

[channels.telegram]
bot_token_env = "TELEGRAM_BOT_TOKEN"
default_agent = "assistant"
allowed_users = [123456789, 987654321]
poll_interval_secs = 1

Discord

Setup: Create a bot at discord.com/developers/applications

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

Slack

Setup: Create an app at api.slack.com/apps with Socket Mode enabled

[channels.slack]
app_token_env = "SLACK_APP_TOKEN"
bot_token_env = "SLACK_BOT_TOKEN"
default_agent = "assistant"
allowed_channels = ["C01234"]

Email (IMAP/SMTP)

Setup: Use app passwords for Gmail/Outlook

[channels.email]
username = "[email protected]"
password_env = "EMAIL_PASSWORD"
imap_host = "imap.gmail.com"
smtp_host = "smtp.gmail.com"
imap_port = 993
smtp_port = 587
default_agent = "assistant"

Setup: Create an app at reddit.com/prefs/apps (script type)

[channels.reddit]
client_id = "abc123def"
client_secret_env = "REDDIT_CLIENT_SECRET"
username = "openfang_bot"
password_env = "REDDIT_PASSWORD"
subreddits = ["openfang", "rust"]
default_agent = "assistant"

Bluesky

Setup: Generate an app password in Settings

[channels.bluesky]
identifier = "user.bsky.social"
app_password_env = "BLUESKY_APP_PASSWORD"
service_url = "https://bsky.social"
default_agent = "assistant"

Enterprise Channels

Microsoft Teams

Setup: Create an Azure Bot registration

[channels.teams]
app_id = "00000000-0000-0000-0000-000000000000"
app_password_env = "TEAMS_APP_PASSWORD"
webhook_port = 3978
default_agent = "assistant"

Mattermost

Setup: Create a bot in System Console > Bot Accounts

[channels.mattermost]
server_url = "https://mattermost.example.com"
token_env = "MATTERMOST_TOKEN"
default_agent = "assistant"
allowed_channels = ["abc123", "def456"]

Developer Channels

IRC

Setup: Choose a server and channel

[channels.irc]
server = "irc.libera.chat"
nick = "openfang"
channels = ["#openfang", "#general"]
port = 6667
use_tls = false
default_agent = "assistant"

Discourse

Setup: Generate an API key in Admin > API

[channels.discourse]
base_url = "https://forum.example.com"
api_key_env = "DISCOURSE_API_KEY"
api_username = "system"
categories = ["general", "support"]
default_agent = "assistant"

Notification Channels

ntfy

Setup: Just pick a topic name

[channels.ntfy]
topic = "openfang-alerts"
server_url = "https://ntfy.sh"
default_agent = "assistant"

Webhook

Setup: Optional HMAC secret for verification

[channels.webhook]
secret_env = "WEBHOOK_SECRET"
listen_port = 8460
default_agent = "assistant"

Field Types

Channel configuration fields use these types:

secret - Password/token (stored in environment variables)
text - Plain text input
number - Numeric value (port, interval, etc.)
list - Comma-separated list

Security

Never store API keys directly in config.toml. Always use environment variables referenced by *_env fields.

Whitelists

Use allowed_users and allowed_channels to restrict access

HMAC Signing

Webhook channel supports HMAC-SHA256 for payload verification

Environment Variables

All secrets referenced via *_env fields (e.g., bot_token_env)

Audit Trail

Channel events logged to kernel audit trail

Bridge Manager

The bridge manager coordinates all active channel adapters:

Hot-reload: Changes apply without restarting
Error recovery: Automatic reconnection on failure
Message routing: Routes messages to correct agents

Next Steps

Agents API

Route channel messages to agents

Workflows API

Build multi-channel workflows

REST API

CLI Reference

OpenAI Compatibility

​Overview

​Channel Categories

Messaging (12)

Social (5)

Enterprise (10)

Developer (9)

Notifications (4)

​List Channels

​Configure Channel

​Common Fields

​Remove Channel

​Test Channel

​Reload Channels

​WhatsApp QR Login

​Start QR Session

​Get QR Status

​Messaging Channels

​Telegram

​Discord

​Slack

​Email (IMAP/SMTP)

​Social Channels

​Reddit

​Bluesky

​Enterprise Channels

​Microsoft Teams

​Mattermost

​Developer Channels

​IRC

​Discourse

​Notification Channels

​ntfy

​Webhook

​Field Types

​Security

Whitelists

HMAC Signing

Environment Variables

Audit Trail

​Bridge Manager

​Next Steps

Agents API

Workflows API

Overview

Channel Categories

List Channels

Configure Channel

Common Fields

Remove Channel

Test Channel

Reload Channels

WhatsApp QR Login

Start QR Session

Get QR Status

Messaging Channels

Telegram

Discord

Slack

Email (IMAP/SMTP)

Social Channels

Reddit

Bluesky

Enterprise Channels

Microsoft Teams

Mattermost

Developer Channels

IRC

Discourse

Notification Channels

ntfy

Webhook

Field Types

Security

Bridge Manager

Next Steps