Channel Adapters - OpenFang

OpenFang connects to messaging platforms through 40 channel adapters, allowing users to interact with agents across every major communication platform. All adapters share common features: graceful shutdown, exponential backoff, secret zeroization, automatic message splitting, per-channel overrides, DM/group policies, rate limiting, and output formatting.

All 40 Supported Channels

Core Messaging (7)

Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Email

Enterprise (8)

Microsoft Teams, Mattermost, Google Chat, Webex, Feishu/Lark, Rocket.Chat, Zulip, XMPP

Social (8)

LINE, Viber, Facebook Messenger, Mastodon, Bluesky, Reddit, LinkedIn, Twitch

Community (6)

IRC, Guilded, Revolt, Keybase, Discourse, Gitter

Privacy (3)

Threema, Nostr, Mumble

Workplace (4)

Pumble, Flock, Twist, DingTalk

Notification (2)

ntfy, Gotify

Integration (2)

Webhook (Generic HTTP), Nextcloud Talk

Quick Start — Core Channels

Prerequisites

A Telegram bot token from @BotFather

Setup

Open Telegram and message @BotFather
Send /newbot and follow the prompts
Copy the bot token

export TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz

Configuration

[channels.telegram]
bot_token_env = "TELEGRAM_BOT_TOKEN"
default_agent = "assistant"
# Optional: restrict to specific user IDs
# allowed_users = ["123456789"]

[channels.telegram.overrides]
# Telegram-native HTML formatting
output_format = "telegram_html"
group_policy = "mention_only"

How It Works

Long-polling via getUpdates API. Polls every few seconds with 30-second timeout. Messages from authorized users route to the configured agent. Responses sent via sendMessage API. Long messages automatically split at Telegram’s 4096-character limit.

Prerequisites

A Discord application and bot from Discord Developer Portal

Setup

Go to Discord Developer Portal
Click “New Application” and name it
Go to Bot section and click “Add Bot”
Copy the bot token
Enable Message Content Intent (required)
Generate OAuth2 URL with bot scope + Send Messages, Read Message History permissions

export DISCORD_BOT_TOKEN=MTIzNDU2Nzg5.ABCDEF.ghijklmnop

Configuration

[channels.discord]
bot_token_env = "DISCORD_BOT_TOKEN"
default_agent = "coder"

How It Works

Connects to Discord Gateway via WebSocket (v10). Listens for MESSAGE_CREATE events and routes to configured agent. Handles Gateway reconnection, heartbeating, and session resumption automatically.

Prerequisites

A Slack app with Socket Mode enabled

Setup

Go to Slack API and create a new app
Enable Socket Mode and generate an App-Level Token (xapp-...) with scope connections:write
Add Bot Token Scopes: chat:write, app_mentions:read, im:history, im:read, im:write
Install the app to your workspace
Copy the Bot User OAuth Token (xoxb-...)

export SLACK_APP_TOKEN=xapp-1-...
export SLACK_BOT_TOKEN=xoxb-...

Configuration

[channels.slack]
bot_token_env = "SLACK_BOT_TOKEN"
app_token_env = "SLACK_APP_TOKEN"
default_agent = "ops"

[channels.slack.overrides]
output_format = "slack_mrkdwn"
threading = true  # Reply in threads

How It Works

Uses Socket Mode (WebSocket) to avoid public webhook URL. Receives events (app mentions, DMs) and routes to configured agent. Responses posted via chat.postMessage. When threading = true, replies sent to message’s thread.

Prerequisites

Meta Business account with WhatsApp Cloud API access

Setup

Go to Meta for Developers
Create a Business App
Add the WhatsApp product
Copy Phone Number ID, Permanent Access Token, and choose a Verify Token

export WA_PHONE_ID=123456789012345
export WA_ACCESS_TOKEN=EAABs...
export WA_VERIFY_TOKEN=my-secret-verify-token

Configuration

[channels.whatsapp]
mode = "cloud_api"
phone_number_id_env = "WA_PHONE_ID"
access_token_env = "WA_ACCESS_TOKEN"
verify_token_env = "WA_VERIFY_TOKEN"
webhook_port = 8443
default_agent = "assistant"

Webhook Setup

Set up webhook in Meta dashboard:

URL: https://your-domain.com:8443/webhook/whatsapp
Verify Token: your chosen value
Subscribe to: messages

How It Works

Runs HTTP server on configured port to receive webhooks from WhatsApp Cloud API. Handles webhook verification (GET) and message reception (POST). Sends responses via Cloud API’s messages endpoint.

Prerequisites

Matrix homeserver account and access token

Setup

Create a bot account on your Matrix homeserver
Generate an access token

export MATRIX_TOKEN=syt_...

Configuration

[channels.matrix]
homeserver_url = "https://matrix.org"
access_token_env = "MATRIX_TOKEN"
user_id = "@openfang-bot:matrix.org"
default_agent = "assistant"

How It Works

Uses Matrix Client-Server API. Syncs with homeserver using long-polling (/sync with timeout). Processes new messages from joined rooms. Responses sent via /rooms/{roomId}/send endpoint.

Prerequisites

Email account with IMAP and SMTP access

Setup

For Gmail, create an App Password.

export EMAIL_PASSWORD=abcd-efgh-ijkl-mnop

Configuration

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

How It Works

Polls IMAP inbox at configured interval. New emails parsed (subject + body) and routed to configured agent. Responses sent as reply emails via SMTP, preserving subject line threading.

Channel Configuration

All channels are configured in ~/.openfang/config.toml under the [channels] section:

[channels.telegram]
bot_token_env = "TELEGRAM_BOT_TOKEN"
default_agent = "assistant"
allowed_users = ["123456789"]

[channels.discord]
bot_token_env = "DISCORD_BOT_TOKEN"
default_agent = "coder"

[channels.slack]
bot_token_env = "SLACK_BOT_TOKEN"
app_token_env = "SLACK_APP_TOKEN"
default_agent = "ops"

Common Configuration Fields

bot_token_env

string

required

Environment variable holding the bot/access token. All secrets stored as Zeroizing<String> and wiped from memory on drop.

default_agent

string

Agent name or ID that receives messages when no specific routing applies.

allowed_users

array

Optional list of platform user IDs allowed to interact. Empty means allow all.

overrides

object

Per-channel behavior overrides (see Channel Overrides section below).

Channel Overrides

Customize agent behavior per channel without modifying agent manifests:

[channels.telegram.overrides]
model = "gemini-2.5-flash"              # Override LLM model
system_prompt = "Brief responses only"  # Override system prompt
dm_policy = "respond"                   # How to handle DMs
group_policy = "mention_only"           # How to handle group messages
rate_limit_per_user = 10                # Max messages per minute per user
threading = true                        # Send replies as threads
output_format = "telegram_html"         # Output format for this channel
usage_footer = "compact"                # Usage info display

Override Fields

model

string

Override the LLM model for this channel. Uses agent’s default if not set.

system_prompt

string

Override the system prompt for this channel.

dm_policy

string

default:"respond"

How to handle direct messages:

respond — Respond to all DMs (default)
allowed_only — Only respond to DMs from users in allowed_users
ignore — Silently drop all DMs

group_policy

string

default:"mention_only"

How to handle group/channel messages:

all — Respond to all messages in the group
mention_only — Only respond when bot is @mentioned (default)
commands_only — Only respond to /command messages
ignore — Ignore all group messages

rate_limit_per_user

number

default:0

Max messages per minute per user. 0 = unlimited. Uses sliding-window rate limiter.

threading

boolean

default:false

Send replies as thread responses on platforms that support it (Slack, Discord, etc.).

output_format

string

default:"markdown"

Output format for this channel:

markdown — Standard Markdown (default)
telegram_html — Telegram HTML subset (, , <code>)
slack_mrkdwn — Slack mrkdwn format (*bold*, _italic_, `code`)
plain_text — No formatting markup

usage_footer

string

Override usage footer mode for this channel: off, tokens, cost, or full.

Output Formatter

The formatter converts Markdown output from the LLM into platform-native formats:

Markdown (Default)
Telegram HTML
Slack Mrkdwn
Plain Text

Standard Markdown passed through as-is. Works on most platforms.

Converts Markdown to Telegram’s HTML subset:

**bold** → bold
*italic* → italic
`code` → <code>code</code>
```block``` → <pre>block</pre>

Converts to Slack’s formatting:

**bold** → *bold*
*italic* → _italic_
Links → <url|text>

Rate Limiting

Per-user rate limiting uses a sliding-window algorithm. When rate_limit_per_user is set, the limiter tracks message counts per user. Excess messages receive a polite rejection. Rate limits are enforced before messages reach the agent loop, consuming zero LLM tokens.

DM and Group Policies

Policy enforcement happens in dispatch_message() before messages reach the agent:

DM Policy Behavior

Policy	Behavior
`respond`	Respond to all DMs (default)
`allowed_only`	Only respond to DMs from users in `allowed_users`
`ignore`	Silently drop all DMs

Group Policy Behavior

Policy	Behavior
`all`	Respond to every message in the group
`mention_only`	Only respond when bot is @mentioned (default)
`commands_only`	Only respond to `/command` messages
`ignore`	Silently ignore all group messages

Ignored messages consume zero LLM tokens since they’re filtered before reaching the agent.

Enterprise Channels

Microsoft Teams

Protocol: Bot Framework v3 webhook + OAuth2Environment Variables:

TEAMS_APP_ID — Azure Bot App ID
TEAMS_APP_PASSWORD — Azure Bot Framework app password

Configuration:

[channels.teams]
app_id = ""
app_password_env = "TEAMS_APP_PASSWORD"
webhook_port = 3978
allowed_tenants = []  # Empty = allow all
default_agent = "ops"

Mattermost

Protocol: WebSocket + REST v4Environment Variables:

MATTERMOST_TOKEN — Bot token
MATTERMOST_URL — Server URL

Configuration:

[channels.mattermost]
server_url = "https://mattermost.example.com"
token_env = "MATTERMOST_TOKEN"
allowed_channels = []  # Empty = all
default_agent = "assistant"

Google Chat

Protocol: Service account webhookEnvironment Variables:

GOOGLE_CHAT_SERVICE_ACCOUNT — Service account JSON key

Configuration:

[channels.google_chat]
service_account_env = "GOOGLE_CHAT_SERVICE_ACCOUNT"
space_ids = []  # Google Chat space IDs
webhook_port = 8444
default_agent = "assistant"

Webex

Environment Variables: WEBEX_BOT_TOKEN

[channels.webex]
bot_token_env = "WEBEX_BOT_TOKEN"
allowed_rooms = []

Feishu / Lark

Environment Variables: FEISHU_APP_ID, FEISHU_APP_SECRET

[channels.feishu]
app_id = ""
app_secret_env = "FEISHU_APP_SECRET"
webhook_port = 8453

Mastodon

Protocol: Streaming API WebSocket

[channels.mastodon]
instance_url = "https://mastodon.social"
access_token_env = "MASTODON_ACCESS_TOKEN"
default_agent = "social-media"

Bluesky

Protocol: AT Protocol WebSocket

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

Protocol: OAuth2 polling

[channels.reddit]
client_id = ""
client_secret_env = "REDDIT_CLIENT_SECRET"
username = ""
password_env = "REDDIT_PASSWORD"
subreddits = []

Twitch

Protocol: IRC gateway

[channels.twitch]
oauth_token_env = "TWITCH_OAUTH_TOKEN"
channels = ["mychannel"]
nick = "openfang"

Privacy-Focused Channels

Signal
Threema
Nostr

Protocol: signal-cli REST/JSON-RPC

[channels.signal]
api_url = "http://localhost:8080"
phone_number = ""
allowed_users = []

Setup: Requires signal-cli running as a service

Protocol: Gateway API webhook

[channels.threema]
threema_id = ""
secret_env = "THREEMA_SECRET"
webhook_port = 8454

Protocol: NIP-01 relay WebSocket

[channels.nostr]
private_key_env = "NOSTR_PRIVATE_KEY"  # nsec or hex format
relays = ["wss://relay.damus.io"]

Agent Routing

The AgentRouter determines which agent receives incoming messages:

Per-channel default — Each channel config has a default_agent field
User-agent binding — Users previously associated with specific agents route to those agents
Command prefix — Users can switch agents: /agent coder
Fallback — Messages go to the first available agent

Environment Variables Reference

TELEGRAM_BOT_TOKEN

string

Telegram Bot API token from @BotFather

DISCORD_BOT_TOKEN

string

Discord bot token

SLACK_BOT_TOKEN

string

Slack bot token (xoxb-) for REST API

SLACK_APP_TOKEN

string

Slack app-level token (xapp-) for Socket Mode

WHATSAPP_ACCESS_TOKEN

string

WhatsApp Cloud API access token

WHATSAPP_VERIFY_TOKEN

string

Webhook verification token

MATRIX_ACCESS_TOKEN

string

Matrix homeserver access token

EMAIL_PASSWORD

string

Email account password or app password

TEAMS_APP_PASSWORD

string

Azure Bot Framework app password

MATTERMOST_TOKEN

string

Mattermost bot token

See full environment variable reference in configuration.md for all 40 channels.

Security

All secrets wrapped in Zeroizing<String> — wiped from memory on drop
Subprocess environment cleared with env_clear() — only whitelisted vars passed through
Webhook endpoints validate signatures (HMAC-SHA256) where supported
Rate limiting protects against abuse
Policy enforcement happens before agent loop — ignored messages consume zero LLM tokens

Get Started

Core Concepts

Autonomous Hands

Configuration

Guides

Security

Deployment

​All 40 Supported Channels

Core Messaging (7)

Enterprise (8)

Social (8)

Community (6)

Privacy (3)

Workplace (4)

Notification (2)

Integration (2)

​Quick Start — Core Channels

​Prerequisites

​Setup

​Configuration

​How It Works

​Prerequisites

​Setup

​Configuration

​How It Works

​Prerequisites

​Setup

​Configuration

​How It Works

​Prerequisites

​Setup

​Configuration

​Webhook Setup

​How It Works

​Prerequisites

​Setup

​Configuration

​How It Works

​Prerequisites

​Setup

​Configuration

​How It Works

​Channel Configuration

​Common Configuration Fields

​Channel Overrides

​Override Fields

​Output Formatter

​Rate Limiting

​DM and Group Policies

​DM Policy Behavior

​Group Policy Behavior

​Enterprise Channels

​Social Platforms

​Privacy-Focused Channels

​Agent Routing

​Environment Variables Reference

​Security

Build docs developers (and LLMs) love

All 40 Supported Channels

Quick Start — Core Channels

Prerequisites

Setup

Configuration

How It Works

Prerequisites

Setup

Configuration

How It Works

Prerequisites

Setup

Configuration

How It Works

Prerequisites

Setup

Configuration

Webhook Setup

How It Works

Prerequisites

Setup

Configuration

How It Works

Prerequisites

Setup

Configuration

How It Works

Channel Configuration

Common Configuration Fields

Channel Overrides

Override Fields

Output Formatter

Rate Limiting

DM and Group Policies

DM Policy Behavior

Group Policy Behavior

Enterprise Channels

Social Platforms

Privacy-Focused Channels

Agent Routing

Environment Variables Reference

Security