Channel Adapters

LibreFang connects to messaging platforms through 40 channel adapters, allowing users to interact with their agents across every major communication platform. Adapters span consumer messaging, enterprise collaboration, social media, community platforms, privacy-focused protocols, and generic webhooks.

All adapters share a common foundation: graceful shutdown via watch::channel, exponential backoff on connection failures, Zeroizing<String> for secrets, automatic message splitting for platform limits, per-channel model/prompt overrides, DM/group policy enforcement, per-user rate limiting, and output formatting (Markdown, TelegramHTML, SlackMrkdwn, PlainText).

Table of Contents

• All 40 Channels
• Channel Configuration
• Channel Overrides
• Formatter, Rate Limiter, and Policies
• Telegram
• Discord
• Slack
• WhatsApp
• Signal
• Matrix
• Email
• WebChat (Built-in)
• Agent Routing
• Writing Custom Adapters

All 40 Channels

Core (7)

Enterprise (8)

Social (8)

Community (6)

Self-hosted (1)

Privacy (3)

Workplace (4)

Notification (2)

Integration (1)

Channel Configuration

All channel configurations live in ~/.librefang/config.toml under the [channels] section. Each channel is a subsection:

[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"

# Enterprise example
[channels.teams]
app_id_env = "TEAMS_APP_ID"
app_secret_env = "TEAMS_APP_SECRET"
default_agent = "ops"

# Social example
[channels.mastodon]
token_env = "MASTODON_TOKEN"
instance = "https://mastodon.social"
default_agent = "social-media"

Common Fields

• bot_token_env / token_env -- The environment variable holding the bot/access token. LibreFang reads the token from this env var at startup. All secrets are stored as Zeroizing<String> and wiped from memory on drop.
• default_agent -- The agent name (or ID) that receives messages when no specific routing applies.
• allowed_users -- Optional list of platform user IDs allowed to interact. Empty means allow all.
• overrides -- Optional per-channel behavior overrides (see Channel Overrides below).

Environment Variables Reference (Core Channels)

Env vars for all other channels are listed in the All 40 Channels tables above.

Channel Overrides

Every channel adapter supports ChannelOverrides, which let you customize behavior per channel without modifying the agent manifest. Add an [channels.<name>.overrides] section in config.toml:

[channels.telegram.overrides]
model = "gemini-2.5-flash"
system_prompt = "You are a concise Telegram assistant. Keep replies under 200 words."
dm_policy = "respond"
group_policy = "mention_only"
rate_limit_per_user = 10
threading = true
output_format = "telegram_html"
usage_footer = "compact"

Override Fields

Formatter, Rate Limiter, and Policies

Output Formatter

The formatter module (librefang-channels/src/formatter.rs) converts Markdown output from the LLM into platform-native formats:

Per-User Rate Limiter

The ChannelRateLimiter (librefang-channels/src/rate_limiter.rs) uses a DashMap to track per-user message counts. When rate_limit_per_user is set on a channel's overrides, the limiter enforces a sliding-window cap of N messages per minute. Excess messages receive a polite rejection.

DM Policy

Controls how the adapter handles direct messages:

Group Policy

Controls how the adapter handles messages in group chats, channels, and rooms:

Policy enforcement happens in dispatch_message() before the message reaches the agent loop. This means ignored messages consume zero LLM tokens.

Telegram

Prerequisites

• A Telegram bot token (from @BotFather)

Setup

1. Open Telegram and message @BotFather.
2. Send /newbot and follow the prompts to create a new bot.
3. Copy the bot token.
4. Set the environment variable:

export TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz

5. Add to config:

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

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

6. Restart the daemon:

librefang start

How It Works

The Telegram adapter uses long-polling via the getUpdates API. It polls every few seconds with a 30-second long-poll timeout. On API failures, it applies exponential backoff (starting at 1 second, up to 60 seconds). Shutdown is coordinated via a watch::channel.

Messages from authorized users are converted to ChannelMessage events and routed to the configured agent. Responses are sent back via the sendMessage API. Long responses are automatically split into multiple messages to respect Telegram's 4096-character limit using the shared split_message() utility.

Interactive Setup

librefang channel setup telegram

This walks you through the setup interactively.

Discord

Prerequisites

• A Discord application and bot (from the Discord Developer Portal)

Setup

1. Go to Discord Developer Portal.
2. Click "New Application" and name it.
3. Go to the Bot section and click "Add Bot".
4. Copy the bot token.
5. Under Privileged Gateway Intents, enable:
   • Message Content Intent (required to read message content)
6. Go to OAuth2 > URL Generator:
   • Select scopes: bot
   • Select permissions: Send Messages, Read Message History
   • Copy the generated URL and open it to invite the bot to your server.
7. Set the environment variable:

export DISCORD_BOT_TOKEN=MTIzNDU2Nzg5.ABCDEF.ghijklmnop

8. Add to config:

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

9. Restart the daemon.

How It Works

The Discord adapter connects to the Discord Gateway via WebSocket (v10). It listens for MESSAGE_CREATE events and routes messages to the configured agent. Responses are sent via the REST API's channels/{id}/messages endpoint.

The adapter handles Gateway reconnection, heartbeating, and session resumption automatically.

Slack

Prerequisites

• A Slack app with Socket Mode enabled

Setup

1. Go to Slack API and click "Create New App" > "From Scratch".
2. Enable Socket Mode (Settings > Socket Mode):
   • Generate an App-Level Token with scope connections:write.
   • Copy the token (xapp-...).
3. Go to OAuth & Permissions and add Bot Token Scopes:
   • chat:write
   • app_mentions:read
   • im:history
   • im:read
   • im:write
4. Install the app to your workspace.
5. Copy the Bot User OAuth Token (xoxb-...).
6. Set the environment variables:

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

7. Add to config:

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

[channels.slack.overrides]
# Optional: Slack-native mrkdwn formatting
# output_format = "slack_mrkdwn"
# threading = true

8. Restart the daemon.

How It Works

The Slack adapter uses Socket Mode, which establishes a WebSocket connection to Slack's servers. This avoids the need for a public webhook URL. The adapter receives events (app mentions, direct messages) and routes them to the configured agent. Responses are posted via the chat.postMessage Web API. When threading = true, replies are sent to the message's thread via thread_ts.

WhatsApp

Prerequisites

• A Meta Business account with WhatsApp Cloud API access

Setup

1. Go to Meta for Developers.
2. Create a Business App.
3. Add the WhatsApp product.
4. Set up a test phone number (or use a production one).
5. Copy:
   • Phone Number ID
   • Permanent Access Token
   • Choose a Verify Token (any string you choose)
6. Set environment variables:

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

7. Add to config:

[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"

8. Set up a webhook in the Meta dashboard pointing to your server's public URL:

   • URL: https://your-domain.com:8443/webhook/whatsapp
   • Verify Token: the value you chose above
   • Subscribe to: messages

9. Restart the daemon.

How It Works

The WhatsApp adapter runs an HTTP server (on the configured webhook_port) that receives incoming webhooks from the WhatsApp Cloud API. It handles webhook verification (GET) and message reception (POST). Responses are sent via the Cloud API's messages endpoint.

Signal

Prerequisites

• Signal CLI installed and linked to a phone number

Setup

1. Install signal-cli.
2. Register or link a phone number.
3. Add to config:

[channels.signal]
signal_cli_path = "/usr/local/bin/signal-cli"
phone_number = "+1234567890"
default_agent = "assistant"

4. Restart the daemon.

How It Works

The Signal adapter spawns signal-cli as a subprocess in daemon mode and communicates via JSON-RPC. Incoming messages are read from the signal-cli output stream and routed to the configured agent.

Matrix

Prerequisites

• A Matrix homeserver account and access token

Setup

1. Create a bot account on your Matrix homeserver.
2. Generate an access token.
3. Set the environment variable:

export MATRIX_TOKEN=syt_...

4. Add to config:

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

5. Invite the bot to the rooms you want it to monitor.
6. Restart the daemon.

How It Works

The Matrix adapter uses the Matrix Client-Server API. It syncs with the homeserver using long-polling (/sync with a timeout) and processes new messages from joined rooms. Responses are sent via the /rooms/{roomId}/send endpoint.

Email

Prerequisites

• An email account with IMAP and SMTP access

Setup

1. For Gmail, create an App Password.
2. Set the environment variable:

export EMAIL_PASSWORD=abcd-efgh-ijkl-mnop

3. Add to config:

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

4. Restart the daemon.

How It Works

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

WebChat (Built-in)

The WebChat UI is embedded in the daemon and requires no configuration. When the daemon is running:

http://127.0.0.1:4200/

Features:

• Real-time chat via WebSocket
• Streaming responses (text deltas as they arrive)
• Agent selection (switch between running agents)
• Token usage display
• No authentication required on localhost (protected by CORS)

Agent Routing

The AgentRouter determines which agent receives an incoming message. The routing logic is:

1. Per-channel default: Each channel config has a default_agent field. Messages from that channel go to that agent.
2. User-agent binding: If a user has previously been associated with a specific agent (via commands or configuration), messages from that user route to that agent.
3. Command prefix: Users can switch agents by sending a command like /agent coder in the chat. Subsequent messages will be routed to the "coder" agent.
4. Fallback: If no routing applies, messages go to the first available agent.

Writing Custom Adapters

To add support for a new messaging platform, implement the ChannelAdapter trait. The trait is defined in crates/librefang-channels/src/types.rs.

The ChannelAdapter Trait

pub trait ChannelAdapter: Send + Sync {
    /// Human-readable name of this adapter.
    fn name(&self) -> &str;

    /// The channel type this adapter handles.
    fn channel_type(&self) -> ChannelType;

    /// Start receiving messages. Returns a stream of incoming messages.
    async fn start(
        &self,
    ) -> Result<Pin<Box<dyn Stream<Item = ChannelMessage> + Send>>, Box<dyn std::error::Error>>;

    /// Send a response back to a user on this channel.
    async fn send(
        &self,
        user: &ChannelUser,
        content: ChannelContent,
    ) -> Result<(), Box<dyn std::error::Error>>;

    /// Send a typing indicator (optional -- default no-op).
    async fn send_typing(&self, _user: &ChannelUser) -> Result<(), Box<dyn std::error::Error>> {
        Ok(())
    }

    /// Stop the adapter and clean up resources.
    async fn stop(&self) -> Result<(), Box<dyn std::error::Error>>;

    /// Get the current health status of this adapter (optional -- default returns disconnected).
    fn status(&self) -> ChannelStatus {
        ChannelStatus::default()
    }

    /// Send a response as a thread reply (optional -- default falls back to `send()`).
    async fn send_in_thread(
        &self,
        user: &ChannelUser,
        content: ChannelContent,
        _thread_id: &str,
    ) -> Result<(), Box<dyn std::error::Error>> {
        self.send(user, content).await
    }
}

1. Define Your Adapter

Create crates/librefang-channels/src/myplatform.rs:

use crate::types::{
    ChannelAdapter, ChannelContent, ChannelMessage, ChannelStatus, ChannelType, ChannelUser,
};
use futures::stream::{self, Stream};
use std::pin::Pin;
use tokio::sync::watch;
use zeroize::Zeroizing;

pub struct MyPlatformAdapter {
    token: Zeroizing<String>,
    client: reqwest::Client,
    shutdown: watch::Receiver<bool>,
}

impl MyPlatformAdapter {
    pub fn new(token: String, shutdown: watch::Receiver<bool>) -> Self {
        Self {
            token: Zeroizing::new(token),
            client: reqwest::Client::new(),
            shutdown,
        }
    }
}

impl ChannelAdapter for MyPlatformAdapter {
    fn name(&self) -> &str {
        "MyPlatform"
    }

    fn channel_type(&self) -> ChannelType {
        ChannelType::Custom("myplatform".to_string())
    }

    async fn start(
        &self,
    ) -> Result<Pin<Box<dyn Stream<Item = ChannelMessage> + Send>>, Box<dyn std::error::Error>> {
        // Return a stream that yields ChannelMessage items.
        // Use self.shutdown to detect when the daemon is stopping.
        // Apply exponential backoff on connection failures.
        let stream = stream::empty(); // Replace with your polling/WebSocket logic
        Ok(Box::pin(stream))
    }

    async fn send(
        &self,
        user: &ChannelUser,
        content: ChannelContent,
    ) -> Result<(), Box<dyn std::error::Error>> {
        // Send the response back to the platform.
        // Use split_message() if the platform has message length limits.
        // Use self.client and self.token to call the platform's API.
        Ok(())
    }

    async fn stop(&self) -> Result<(), Box<dyn std::error::Error>> {
        // Clean shutdown: close connections, stop polling.
        Ok(())
    }

    fn status(&self) -> ChannelStatus {
        ChannelStatus::default()
    }
}

Key points for new adapters:

• Use ChannelType::Custom("myplatform".to_string()) for the channel type. Only the 9 most common channels have named ChannelType variants (Telegram, WhatsApp, Slack, Discord, Signal, Matrix, Email, Teams, Mattermost). All others use Custom(String).
• Wrap secrets in Zeroizing<String> so they are wiped from memory on drop.
• Accept a watch::Receiver<bool> for coordinated shutdown with the daemon.
• Use exponential backoff for resilience on connection failures.
• Use the shared split_message(text, max_len) utility for platforms with message length limits.

2. Register the Module

In crates/librefang-channels/src/lib.rs:

pub mod myplatform;

3. Wire It Into the Bridge

In crates/librefang-api/src/channel_bridge.rs, add initialization logic for your adapter alongside the existing adapters.

4. Add Config Support

In librefang-types, add a config struct:

#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct MyPlatformConfig {
    pub token_env: String,
    pub default_agent: Option<String>,
    #[serde(default)]
    pub overrides: ChannelOverrides,
}

Add it to the ChannelsConfig struct and config.toml parsing. The overrides field gives your channel automatic support for model/prompt overrides, DM/group policies, rate limiting, threading, and output format selection.

5. Add CLI Setup Wizard

In crates/librefang-cli/src/main.rs, add a case to cmd_channel_setup with step-by-step instructions for your platform.

6. Test

Write integration tests. Use the ChannelMessage type to simulate incoming messages without connecting to the real platform.

7. Add Feature Flag

Since PR #223, each channel adapter is gated behind a Cargo feature flag for smaller binary sizes.

In crates/librefang-channels/Cargo.toml:

[features]
channel-myplatform = []  # Add your channel feature

Gate your module in lib.rs:

#[cfg(feature = "channel-myplatform")]
pub mod myplatform;

Forward the feature through crates/librefang-api/Cargo.toml and crates/librefang-cli/Cargo.toml:

[features]
channel-myplatform = ["librefang-channels/channel-myplatform"]

If your adapter needs platform-specific dependencies (e.g., a client library), make them optional and tie them to your feature flag:

[dependencies]
myplatform-sdk = { version = "1.0", optional = true }

[features]
channel-myplatform = ["myplatform-sdk"]

When a user configures a channel whose feature is disabled, LibreFang emits a tracing::warn at startup instead of failing silently.

Example: Contributing a New Channel Adapter

Here's a step-by-step checklist for contributing a new channel adapter:

1. Create crates/librefang-channels/src/myplatform.rs implementing ChannelAdapter
2. Register the module in lib.rs (with #[cfg(feature = "channel-myplatform")])
3. Add feature flag in Cargo.toml (channels → api → cli chain)
4. Add config struct in librefang-types
5. Wire into channel_bridge.rs
6. Add CLI setup wizard step
7. Write integration tests
8. Update the channel count in README.md and docs

See the examples/custom-channel/ directory in the main repo for a reference template.