Wiki · Integrations
Telegram — running the bot
The most common Telegram problem is not Hermes but the bot's privacy mode. Practical: setup, groups and delivery.
The quick path
In the dashboard (Messaging → Telegram) and in the desktop app there is a Create with QR
button: scan the code, Hermes creates the bot, detects your numeric ID and writes
TELEGRAM_BOT_TOKEN and TELEGRAM_ALLOWED_USERS into .env for you.
The manual path below is for those who want the bot under their own control — and it is worth knowing
what happens along it.
1. The bot at BotFather
The token is the key to the bot. Whoever holds it controls the bot. If it leaks,
revoke it with /revoke at BotFather and replace it in .env.
| BotFather command | Purpose |
|---|---|
/setdescription | The “What can this bot do?” text before the first message |
/setcommands | The command menu behind the “/” button (help, new, sethome is plenty) |
/setuserpic | Bot avatar |
/setprivacy | That privacy mode — see below |
2. Privacy mode: why the bot “cannot see” in groups
Privacy mode is on by default. The bot then receives only:
- messages starting with
/(commands), - replies to its own messages,
- service messages (joins/leaves, pins),
- everything in groups where it is an admin.
An alternative without touching privacy mode: make the bot a group admin. Admins receive all messages and you do not have to change a global setting.
Listen but do not answer
The bot follows the conversation (so it can summarise what was discussed) but speaks only when mentioned or called by a command.
3. Numeric ID and access
Hermes gates access by numeric ID, not by username (usernames can change).
Get yours by messaging @userinfobot.
An empty TELEGRAM_ALLOWED_USERS means the bot answers anyone who finds it.
Never leave that on a personal agent — always list at least your own ID.
4. What it can do
| Feature | How it shows up |
|---|---|
| Voice messages | Incoming ones are transcribed; the agent can reply with voice when TTS is on |
| Files and photos | Sends and receives attachments; a MEDIA:/… path must be readable where the gateway runs |
| Scheduled delivery | Cron results arrive in the home channel (/sethome or TELEGRAM_HOME_CHANNEL) |
| Topics (threads) | In topic-enabled groups you can pin which topic cron posts into (TELEGRAM_CRON_THREAD_ID) |
| Reactions | The agent can acknowledge a message with a reaction instead of a reply |
| Files above 20 MB | Only via your own Bot API server (TELEGRAM_LOCAL, TELEGRAM_API_ID, TELEGRAM_API_HASH) |
| Webhook instead of polling | With a public HTTPS address (TELEGRAM_WEBHOOK_URL, …_SECRET, …_PORT) |
5. Several bots in one group
It works, but each bot needs its own token and profile. To stop them talking over each other, give
them distinct trigger phrases (mention_patterns) or separate topics — otherwise both answer
the same message.
Common problems
| Symptom | Cause |
|---|---|
| Works in DMs, silent in groups | Privacy mode (above) — turn it off, or make the bot an admin |
| Still nothing after turning privacy mode off | Remove the bot from the group and add it again |
| The bot never answers | The gateway is not running (hermes gateway status) or your ID is not in the allowlist |
| “Unauthorized” in the log | Wrong or revoked token; after /revoke you need a new one |
| An attachment never arrives | The gateway runs in Docker and the MEDIA: path exists only inside the container |
| Files above 20 MB fail | A limit of the public Bot API — you need your own Bot API server |
How we run it
We use Telegram as a remote control: a cron summary in the morning, questions from the phone during the day, and results (tables, PDFs) coming back as attachments. Two habits paid off:
| Habit | Why |
|---|---|
| Set the home channel right away | Without it cron has nowhere to post and results get lost |
| Keep the allowlist to our own IDs | The bot is publicly discoverable; the allowlist is the only gate |