Telegram

Autobot connects to Telegram via the Bot API using long polling. No webhook or public IP needed.

Setup

1. Create a bot

Open Telegram and message @BotFather:

1. Send /newbot
2. Choose a display name (e.g. "My Autobot")
3. Choose a username (must end in bot, e.g. my_autobot_bot)
4. Copy the bot token (123456:ABC-DEF...)

2. Get your user ID

Message @userinfobot — it replies with your numeric user ID (e.g. 123456789).

3. Configure

Add the token to your .env file:

TELEGRAM_BOT_TOKEN=123456:ABC-DEF...

In config.yml:

channels:
  telegram:
    enabled: true
    token: "${TELEGRAM_BOT_TOKEN}"
    allow_from: ["123456789"]  # your user ID

4. Start

autobot agent
# Should show: Telegram bot @my_autobot_bot connected

Open a chat with your bot in Telegram and send a message.

Access control

allow_from controls who can interact with the bot. It accepts Telegram user IDs and usernames:

# Deny all (secure default)
allow_from: []

# Allow specific users (recommended)
allow_from: ["123456789", "username"]

# Allow anyone (use with caution)
allow_from: ["*"]

Telegram sends both numeric user ID and username. The bot matches against both — "123456789" and "johndoe" both work.

Unauthorized users receive a friendly denial message with their user ID, so they can share it with you to be added.

Custom commands

Add custom slash commands that appear in Telegram's command menu:

channels:
  telegram:
    enabled: true
    token: "${TELEGRAM_BOT_TOKEN}"
    allow_from: ["123456789"]
    custom_commands:
      macros:
        summarize: "Summarize the last conversation in 3 bullet points"
        translate:
          prompt: "Translate the following to English"
          description: "Translate text to English"
      scripts:
        deploy:
          path: "/home/user/scripts/deploy.sh"
          description: "Deploy to production"

Macros send the prompt to the LLM. Scripts execute a shell command and send its output as plain text, exactly as printed: nothing in it is interpreted as formatting, and < and & are escaped. A script that fails gets Script failed (exit N): followed by its stderr.

Built-in commands

Command	Description
/start	Welcome message
/reset	Clear conversation history
/help	List available commands

Features

• Long polling — no webhook or public IP needed
• Reply context and quotes — when replying to a message or selecting a quote excerpt, the replied-to text is prepended as context so the bot understands the reference
• Voice notes — a note recorded in the chat is transcribed via Whisper into the message text (Groq or OpenAI key, or the bot's own transcription.api_key); with transcription off the bot replies that it could not hear the note
• Audio files and forwarded voice notes — saved to the inbox as attachments; the transcript stays on the attachment, never in the message text
• Photos and uncompressed image documents — sent as image attachments to the LLM and saved to the inbox (uncompressed documents with image/* MIME types are automatically ingested for vision)
• Documents — saved to the inbox and attached to the message context
• Forwards and stories — forwarded messages and shared stories preserve sender attribution and origin metadata
• Polls, locations, and venues — questions, choices, GPS coordinates, and venue details are formatted into prompt context
• Contacts — shared contact cards format name and phone details
• Rich message articles — Bot API rich message blocks (headings, blockquotes, fenced code with language, and lists) are converted into Markdown
• Typing indicators — shows "typing..." from the incoming message until the turn ends, whether or not the turn produced a reply
• Markdown rendering — LLM responses are converted to Telegram HTML
• Group chats — the bot only replies when addressed: mentioned by @username or replied to. Other group messages are ignored (no response, no access-denied notice).
• Forum topics — in a group with topics enabled, a bot answers every message in the topics listed under topics without a mention, keeps one session per topic and replies into the same topic. See Forum topics.
• Voice replies — the text_to_speech plugin can generate spoken replies (see Plugins)

Group chat logging

Every message in a group the bot is a member of is appended to a rolling per-chat log at data/chat_logs/telegram_<chat_id>.log, whether or not it addresses the bot. The log is capped in size and only the most recent messages are retained. The get_recent_chat_log tool reads these logs so the bot can consult recent discussion. Operators should be aware this persists group members' messages to disk; disable the chat_log plugin to turn it off.

Configuration reference

Field	Required	Default	Description
enabled	No	false	Enable the Telegram channel
token	Yes	—	Bot API token from BotFather
allow_from	No	[]	User IDs/usernames allowed to use the bot
topics	No	[]	Forum topic IDs the bot owns; it answers there without a mention
proxy	No	—	HTTP proxy URL for API requests
custom_commands	No	—	Custom slash commands (macros and scripts)

Forum topics

A supergroup with topics enabled behaves like several chats in one window. Give each bot its own topic:

channels:
  telegram:
    enabled: true
    token: "${TELEGRAM_BOT_TOKEN}"
    allow_from: ["username"]
    topics: [57]

• The topic ID is the number at the end of the topic link, https://t.me/c/<group>/57.
• Messages in a listed topic are treated as addressed to the bot; other topics still need a mention. The General topic is topic 1: topics: [1] gives a bot the General topic, and replies there carry no thread id, as Telegram expects.
• The chat ID becomes <group>:<topic>, for example -1001234567890:57, so each topic has its own session, its own /reset and its own cron delivery target. Use that form as the to of a cron job or a message tool call to reach a topic.
• The bot must see the topic's messages: turn off privacy mode for it in BotFather (/setprivacy), or make it a group admin, then remove and re-add it to the group.
• Service messages, such as a member joining, a pinned message or a topic being created, are ignored, so owning a topic never makes the bot comment on them.
• A command in a group is handled by the bot it names, as in /help@mybot, or, without a name, by the bot that owns the topic or is mentioned; other bots stay silent. An unknown command gets a one-line reply pointing to /help.

Troubleshooting

Enable debug logging:

LOG_LEVEL=DEBUG autobot agent

Bot doesn't respond — check allow_from contains your user ID. The log shows Access denied for sender <id> with the exact ID to add.

"Telegram bot token not configured" — token is empty. Check .env file and ${TELEGRAM_BOT_TOKEN} substitution.

Bot replies that it could not hear a voice note — transcription is off or no Whisper key is available. Add a Groq or OpenAI provider, or set transcription.api_key; see Voice transcription. autobot doctor shows which provider is in use.