Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.feral.sh/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Telegram channel lets you interact with FERAL through direct messages or group chats. Messages are relayed to the brain over WebSocket — FERAL responds with text, SDUI cards, or voice notes depending on context.

​
Setup

1

Create a bot with BotFather

Open Telegram and message @BotFather:
/newbot
Follow the prompts to name your bot. BotFather returns a token like:
7204381:AAH3k9-_xBcMnRqJFfQ2PzL5t...
Copy this token — you’ll need it in the next step.
2

Set the bot token

export FERAL_TELEGRAM_BOT_TOKEN="7204381:AAH3k9-_xBcMnRqJFfQ2PzL5t..."
Prefer the environment variable or credential vault over putting the token directly in settings.json.
3

Configure bot settings (optional)

Customize behavior in settings.json:
{
  "channels": {
    "telegram": {
      "enabled": true,
      "allowed_user_ids": [123456789],
      "allow_groups": true,
      "group_trigger": "@feralbot",
      "max_message_length": 4096,
      "send_typing_indicator": true
    }
  }
}
SettingDefaultDescription
allowed_user_ids[] (all)Restrict access to specific Telegram user IDs
allow_groupsfalseWhether the bot responds in group chats
group_trigger"@feralbot"Mention prefix required in groups
send_typing_indicatortrueShow “typing…” while the brain processes
4

Restart FERAL

feral stop && feral start
5

Test the connection

Open Telegram and send a DM to your bot:
Hey FERAL, what's my schedule today?
You should see a response within a few seconds. Check the REPL or dashboard for the relayed message.

​
Group Chat Usage

When allow_groups is true, add the bot to any Telegram group. By default, the bot only responds when mentioned: 
@feralbot dim the lights to 20%
To let the bot read all group messages (for proactive suggestions), disable privacy mode via BotFather: /setprivacy → Disable.

​
Supported Message Types

TypeDirectionDescription
TextBothStandard messages
PhotosIncomingFERAL can analyze images via its vision pipeline
Voice notesIncomingTranscribed via Whisper, then processed as text
SDUI cardsOutgoingRendered as formatted messages with inline buttons
DocumentsIncomingParsed and stored in memory if relevant

​
Troubleshooting

Run feral status and verify the Telegram channel shows as connected. Check that FERAL_TELEGRAM_BOT_TOKEN is set and valid.
Ensure allow_groups is true and the bot’s privacy mode is disabled in BotFather.
If allowed_user_ids is set, only listed IDs can interact. Find your Telegram user ID by messaging @userinfobot.