Skip to main content

​
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:
Follow the prompts to name your bot. BotFather returns a token like:
Copy this token — you’ll need it in the next step.
2

Set the bot token

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:
Earlier versions of this page documented allowed_user_ids, allow_groups, group_trigger, max_message_length and send_typing_indicator as options here. The brain reads none of those keys. Access control for every channel lives in the shared keys below, and the defaults are fail-closed: with no allowlist and no open pairing window, the channel accepts nothing. The old table described [] as “(all)”, which is the opposite of what the code does (channels/base.py:345-362).
A sender that is not allowlisted is recorded and receives no reply at all, so a stranger cannot learn whether a brain is listening (channels/base.py:345-362).
4

Restart FERAL

5

Test the connection

Open Telegram and send a DM to your bot:
You should see a response within a few seconds. Check the REPL or dashboard for the relayed message.

​
Group Chat Usage

Add the bot to a Telegram group, then put that group’s chat id in allowed_chats. There is no separate group toggle: a group is allowed exactly when its chat id is allowlisted.
To let the bot read all group messages (for proactive suggestions), disable privacy mode via BotFather: /setprivacy → Disable.

​
Supported Message Types

​
Troubleshooting

Run feral status and verify the Telegram channel shows as connected. Check that FERAL_TELEGRAM_BOT_TOKEN is set and valid.
Put the group’s chat id in allowed_chats, and disable the bot’s privacy mode in BotFather so it can see group messages.
Only ids in allowed_senders (or chats in allowed_chats) can interact, and an empty allowlist accepts nobody. Find your Telegram user ID by messaging @userinfobot, or open a pairing_window_sec window and message the bot once to bind yourself as owner.