Hermes Agent Telegram bot: setup step by step

Step 1: create the bot with BotFather

Every Telegram bot gets its token from BotFather, Telegram’s official bot for managing bots.

1. In Telegram, open the chat with @BotFather.
2. Send /newbot.
3. Choose a display name. It can be anything.
4. Choose a username. It must be unique and end in bot, for example my_hermes_bot.
5. BotFather replies with a token that looks like 123456789:ABCdefGHIjklMNOpqrSTUvwxYZ.

Treat the token like a password: anyone who has it can control your bot. If it leaks or you lose it, send /token to BotFather to generate a new one, then update the token in Hermes. Optional BotFather commands such as /setdescription, /setabouttext, /setuserpic and /setcommands only change how the bot looks in Telegram.

The Hermes dashboard and desktop app also have a shortcut: on the Messaging, Telegram page, a “Create with QR” button creates the bot for you, finds your Telegram user ID, writes the token and allowed user into your settings and restarts the gateway. The manual steps below work everywhere.

Step 2: give Hermes the token and your user ID

Hermes decides who may use the bot by numeric Telegram user ID, not by username. To find yours, message a bot such as @userinfobot (the Hermes docs also name @get_id_bot); it replies with a number like 123456789.

The guided way is hermes gateway setup: pick Telegram from its list and it asks for the token and the user IDs to allow. Prefer to edit files yourself? Add two lines to ~/.hermes/.env:

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789

Several people can be allowed by separating their IDs with commas. If you have not installed Hermes yet, start with how to install Hermes Agent.

Step 3: start the gateway and keep it running

Telegram works through the Hermes gateway. Run hermes gateway, wait a few seconds, then send your bot a message. By default Hermes reaches Telegram by long polling: the gateway makes outgoing requests to Telegram to fetch new messages, so it needs no public address.

Running it in a terminal stops it when you close the terminal. To keep it going, install it as a service with hermes gateway install (a user service on Linux, a launchd service on macOS), then use hermes gateway start, stop, status and restart. On a Linux server that should come back after a reboot, the Hermes docs also describe a boot-time system service, installed with sudo hermes gateway install --system; its commands take --system and need sudo, so check which kind you installed before running stop or restart. Hermes also has a webhook mode (TELEGRAM_WEBHOOK_URL plus a required TELEGRAM_WEBHOOK_SECRET), where Telegram pushes messages to a public HTTPS address; this can help on hosts that wake when an HTTP request arrives.

One limit applies however you run it: the bot answers only while the machine running the gateway is on and online. If that is a laptop, the bot goes quiet when the lid closes. Telegram keeps undelivered messages for at most 24 hours, and by default Hermes discards messages that piled up while it was off when it starts cold. Setting drop_pending_on_cold_boot: false under the Telegram settings keeps that backlog, though old, time-sensitive commands will then run when the gateway comes back.

So this suits you if you are happy to leave a machine on, such as a small server or a desktop that never sleeps. If you want an agent that answers at 3 a.m. and runs scheduled jobs while your own computer is off, it needs an always-on host: your own server, or a managed one. Our comparison of self-hosting and managed hosting goes through that choice.

Who is allowed to talk to your bot

Anyone on Telegram can find and message a bot, and your agent can run commands and edit files, so access matters. The safe default in Hermes is that the gateway denies everyone who is not on an allowlist or paired. There are three ways to let people in:

• An allowlist: TELEGRAM_ALLOWED_USERS, as above. It covers private chats, groups and forum topics.
• Pairing, for private chats: an unknown person who messages the bot in a private chat gets a one-time code, and you approve it on the machine with hermes pairing approve telegram <code>. hermes pairing list shows pending and approved people, and hermes pairing revoke telegram <user id> removes one. Codes expire after one hour. Pairing is not offered in groups. Note that once an allowlist is set, Hermes by default ignores unknown private messages silently instead of sending a code; to get codes as well, set telegram.unauthorized_dm_behavior: pair.
• Everyone: TELEGRAM_ALLOW_ALL_USERS=true lets any Telegram user trigger the bot. The Hermes docs list it for development only, and it is a poor idea for a bot that can run commands. The general GATEWAY_ALLOW_ALL_USERS flag is only consulted when no allowlist applies.

You can also split allowed people into admins and regular users, so regular users can chat and run only the slash commands you list, plus /help and /whoami, which are always available. /whoami in Telegram shows which tier you are in.

Using it: messages, voice, files and commands

• Voice notes are transcribed and passed to the agent as text, using the speech-to-text provider set in stt.provider (turn it off with stt.enabled: false). The local option runs on the machine that runs Hermes; the hosted options need their own provider credentials. If a voice note is not transcribed, check those two settings first.
• Images and files are supported. Telegram’s public bot interface limits downloads to 20 MB; Hermes can lift that to 2 GB if you run Telegram’s own local bot server and point Hermes at it.
• Commands: Hermes registers a / command menu when the gateway starts (capped at 60 entries by default; /commands lists them all). Useful ones include /new for a fresh conversation, /model to switch model with buttons, /sethome and /whoami.
• Scheduled jobs: /sethome makes the current chat Telegram’s home destination. Jobs set to deliver to Telegram use it; other jobs follow their own delivery settings.
• Approvals: in manual approval mode, commands that Hermes flags can ask for your go-ahead in the chat; follow the prompt to approve or deny.

Groups and privacy mode

Telegram bots have privacy mode switched on by default. In a group, a bot with privacy mode on does not receive ordinary messages (Telegram sends it only certain messages, such as commands addressed to it and replies to its own messages), so it can appear to ignore the chat. To change that, message BotFather, send /mybots, choose the bot, then Bot Settings, Group Privacy, Turn off. Remove the bot from the group and add it again afterwards, because Telegram keeps the old setting for existing memberships. Making the bot a group admin also lets it see all messages.

Telegram is only the first gate. Hermes still checks the sender against TELEGRAM_ALLOWED_USERS, or against TELEGRAM_GROUP_ALLOWED_USERS (people allowed in groups only) or TELEGRAM_GROUP_ALLOWED_CHATS (everyone in a named group). Group chat IDs are negative numbers such as -1001234567890. To stop the bot answering every message, set telegram.require_mention: true: it then replies only to mentions, replies to it, commands addressed to it and any wake-word patterns you configure.

Common errors and fixes

• The bot does not respond at all. Check that TELEGRAM_BOT_TOKEN is correct and read the output of hermes gateway. If you generated a new token in BotFather, update it.
• It says you are unauthorized. Your user ID is not in TELEGRAM_ALLOWED_USERS. Check it with @userinfobot. With an allowlist set, Hermes may ignore unknown private messages silently, as described above.
• It works in a private chat but not in a group. Work through the gates in order: Telegram delivery (privacy mode, admin or mention), re-adding the bot after a privacy change, Hermes authorization, the mention filter, and, if several Hermes bots share the group, a different token for each.
• Voice notes are not transcribed. Check stt.enabled and stt.provider, and that the chosen provider has what it needs (the local option needs a local transcription backend, such as faster-whisper, on the machine running Hermes).
• Telegram is blocked on your network. Set TELEGRAM_PROXY (http, https or socks5) or telegram.proxy_url in the config.
• Replies stop when the computer sleeps. See the end of Step 3.

Telegram on ReadyHermes

On ReadyHermes your own Hermes Agent runs on our servers, always on, so it keeps answering Telegram and running scheduled jobs while your computer is off. There is no gateway for you to start or keep running. You connect Telegram from the workspace:

1. Create a bot in BotFather as in Step 1 and copy its token.
2. In the workspace, open Channels, choose Telegram, paste the token and connect. Your assistant restarts to apply it, which takes about a minute.
3. Message your new bot on Telegram. It replies with a short pairing code. Paste that code into the Channels panel and approve it, so the assistant knows the account is yours.

That is the same pairing step described above, done from a web page instead of a command on your own machine. You can disconnect Telegram from the same panel at any time. The Channels panel needs an active trial or paid plan. Telegram is one of several chat apps there, alongside WhatsApp, Discord, WeChat, Lark and Slack. To see what else is included, read about managed Hermes Agent hosting.