Skip to main content

​
Channels

FERAL connects to external messaging platforms through channels. Each channel bridges a platform’s API into the Brain’s session system, so users can talk to the agent from Telegram, Slack, Discord, or receive push notifications — all with the same capabilities as the web UI.

​
ChannelManager Architecture

The ChannelManager is a singleton that registers, starts, and supervises channel adapters. Each adapter runs in its own asyncio task and translates platform-specific messages into FeralMessage objects. 
from feral_core.channels import ChannelManager

manager = ChannelManager(brain=brain)
manager.register("telegram", TelegramChannel(token="..."))
manager.register("slack", SlackChannel(token="..."))
manager.register("discord", DiscordChannel(token="..."))
await manager.start_all()
Each channel adapter implements a common interface: 
class ChannelAdapter:
    async def start(self) -> None: ...
    async def stop(self) -> None: ...
    async def send(self, user_id: str, message: FeralMessage) -> None: ...
    async def on_message(self, callback: Callable) -> None: ...

​
Telegram Bot

​
Setup

  1. Create a bot via @BotFather and get the token.
  2. Store the token in the vault:
feral vault set TELEGRAM_BOT_TOKEN "123456:ABC-..."
  1. Enable the channel in config:
# ~/.feral/config.yaml
channels:
  telegram:
    enabled: true
    allowed_users:
      - 12345678       # Telegram user IDs
    features:
      voice_messages: true
      inline_mode: true
  1. Start FERAL — the Telegram channel connects automatically.

​
Features

FeatureStatus
Text messagesSupported
Voice messages (transcribed via Whisper)Supported
Photos (analyzed via vision)Supported
Inline mode (use FERAL in any chat)Supported
Group chatsSupported (mention-triggered)
SDUI cards rendered as Telegram messagesSupported

​
Slack Integration

​
Setup

  1. Create a Slack app at api.slack.com/apps.
  2. Enable Socket Mode and add bot scopes: chat:write, app_mentions:read, im:history.
  3. Store tokens:
feral vault set SLACK_BOT_TOKEN "xoxb-..."
feral vault set SLACK_APP_TOKEN "xapp-..."
  1. Configure:
channels:
  slack:
    enabled: true
    socket_mode: true
    respond_to:
      - direct_messages
      - app_mentions
    default_channel: "#general"

​
Thread Support

FERAL maintains session continuity per Slack thread. A new thread starts a new session; replies within a thread continue the same conversation context.

​
Discord Gateway

​
Setup

  1. Create an application at discord.com/developers.
  2. Add a bot, enable Message Content Intent.
  3. Invite the bot to your server with Send Messages + Read Message History permissions.
feral vault set DISCORD_BOT_TOKEN "MTIz..."

channels:
  discord:
    enabled: true
    command_prefix: "!"
    respond_in_channels:
      - "feral-chat"
      - "general"
    respond_to_dms: true

​
Slash Commands

FERAL auto-registers Discord slash commands on startup:
CommandDescription
/ask <question>Ask the agent a question
/remember <fact>Store a fact in memory
/statusShow agent status and uptime
/voiceJoin voice channel (experimental)

​
Push Notifications

FERAL sends push notifications via Firebase Cloud Messaging (Android/web) and Apple Push Notification service (iOS) for proactive alerts, reminders, and task completions.

​
Configuration

channels:
  push:
    enabled: true
    fcm:
      credentials_file: ~/.feral/firebase-credentials.json
    apns:
      key_file: ~/.feral/apns-auth-key.p8
      key_id: "ABC123"
      team_id: "DEF456"
      bundle_id: "io.feral.app"
      environment: production  # or sandbox

​
Sending Notifications

Push notifications are triggered by the Brain when proactive events fire (health alerts, reminders, task completions): 
from feral_core.channels import PushChannel

push = PushChannel(config)

await push.send(
    user_id="user_123",
    message=FeralMessage(
        type="push_notification",
        payload={
            "title": "Hydration Reminder",
            "body": "You haven't logged water in 3 hours.",
            "action_url": "/dashboard",
            "priority": "normal",
        },
    ),
)

​
Device Registration

Clients register their push tokens via the Brain API: 
curl -X POST http://localhost:9090/api/push/register \
  -H "Content-Type: application/json" \
  -d '{"user_id": "user_123", "platform": "fcm", "token": "eKx7..."}'

​
Channel-Specific Formatting

Each adapter translates SDUI payloads into platform-native formatting:
SDUI ComponentTelegramSlackDiscord
MetricCardBold text + emojiBlock Kit sectionEmbed field
DataTableMonospace textBlock Kit tableCode block
FormCardInline keyboardModalButton row
ImageCardPhoto messageImage blockEmbed image
MarkdownCardMarkdown (subset)mrkdwnMarkdown