.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
Telegram is the easiest channel to wire Hermes into. The Bot API is well-documented, BotFather makes registration straightforward and Hermes ships with first-class support for it. The reason this article exists is that the easy path gets you a bot that answers messages 99 percent of the time. The remaining 1 percent (the bot mysteriously stops responding for half an hour, then comes back) is what most people end up troubleshooting two weeks in.
This guide covers the basic setup, the allowlist patterns that prevent randos from running up your LLM bill and the reliability tuning that handles Telegram's occasional rough patches without you having to babysit the gateway.
Register a bot with BotFather
Open Telegram, search for @BotFather, send /newbot. BotFather asks for a display name (anything readable; this is what users see in their chat list) and a username (must end in "bot", must be unique globally; my_hermes_2026_bot is fine if it's free).
BotFather replies with a token in the format 123456789:ABC-DEF1234ghIklZyx57W2v1u123ew11. Copy this; you'll paste it into Hermes shortly. The token is functionally a password for the bot. Treat it like one. If it leaks, anyone can impersonate your bot, so rotate it (BotFather command /revoke) immediately if it ends up in a screenshot, a public git repo or a chat log.
Two BotFather settings to change before you move on. /setprivacy off (so the bot sees all messages in groups, not just commands directed at it). /setjoingroups disabled if you only want one-on-one chat (which is the default for personal-use Hermes setups).
Plug the token into Hermes
Edit ~/.hermes/.env and add:
TELEGRAM_BOT_TOKEN=123456789:ABC-DEF1234ghIklZyx57W2v1u123ew11No quotes around the value. Telegram tokens contain a colon, which some env parsers handle weirdly under quoting. The plain unquoted form is what Hermes expects. If you'd rather paste the token through the dashboard instead of editing files, the Keys screen on the web UI handles it; our Hermes Agent VPS setup guide covers opening the dashboard over an SSH tunnel.
Set the allowed users:
hermes config set messaging.telegram.allowed_users "[123456789]"Replace the number with your own Telegram user ID. To get yours, message @userinfobot on Telegram from the account that should have access; it replies with the numeric ID.
Run the gateway setup wizard, which validates your token by calling Telegram's getMe endpoint:
hermes gateway setupIf the token is valid, the wizard reports the bot's username and you're set. If it returns an error like "401 Unauthorized", the token is wrong; double-check that you copied the entire string from BotFather (the second half after the colon is easy to truncate).
Start the gateway:
hermes gateway startOr if you've followed the systemd guide, just sudo systemctl start hermes.
Send your bot a Telegram message. It should respond within a few seconds. If it doesn't, jump to the troubleshooting section.
The allowed-users list explained
The allowlist is exactly what it sounds like: a list of Telegram numeric user IDs that the bot will respond to. Anyone not on the list gets either silence or a polite "you're not authorised" message, depending on the messaging.telegram.unknown_user_action setting.
Two patterns to know.
For a personal bot, allow only yourself: "[123456789]". The bot ignores everyone else. Cheapest setup; works fine for personal use.
For a small team bot, allow each team member's ID: "[123, 456, 789]". Each person needs to message @userinfobot first to find their ID. The list grows linearly with the team but doesn't have moving parts; just edit the config when someone joins or leaves.
For a public bot (you're running customer support, you've made a public assistant), don't use the allowlist. Instead, configure rate limits and the prompt-injection filter to handle abuse: hermes config set messaging.telegram.rate_limit "20/hour" caps each user to 20 messages per hour. The production hardening guide covers public-bot patterns in more detail.
Bot commands
Telegram lets you register a list of slash commands that show up as a popup menu in the chat. Hermes auto-publishes its slash commands to BotFather on first start, but you can customise:
hermes config set messaging.telegram.commands "
/help - Show what I can do
/reset - Start a fresh conversation
/skills - Browse available skills
/usage - Show your token usage today
"The agent's actual command handling is the same regardless of what's published; the commands config just controls the menu users see in their Telegram client. Customise it to match the slash commands your users need.
The polling-vs-webhook choice
Telegram offers two ways for a bot to receive messages: long polling (the bot calls Telegram in a loop asking "anything new?") and webhooks (Telegram POSTs to your bot when a message arrives).
Hermes defaults to long polling, which is right for most setups. Polling works behind any firewall, doesn't require a public IP and doesn't need TLS. The gateway holds a long-running HTTP request to Telegram and gets messages pushed back over that connection.
If you have a static public IP and HTTPS already set up (per the Nginx guide), webhooks are slightly faster (no polling latency) and use less bandwidth. Switch with:
hermes config set messaging.telegram.mode webhook
hermes config set messaging.telegram.webhook_url "https://hermes.example.com/telegram/webhook"Hermes registers the webhook URL with Telegram on next startup. Telegram requires HTTPS with a valid cert (Let's Encrypt is fine), so make sure your reverse proxy is up before flipping the mode.
For most setups, leave it on polling. Webhooks are nice but not necessary and polling has fewer moving parts to break.
The "Telegram works for a few minutes then goes silent" problem
This is the most common reliability complaint. The symptom: the bot responds fine for the first few hours, then mysteriously stops. journalctl -u hermes -f shows the gateway is still running, no errors, no crashes.
Three things to check, in order.
First: is another process polling the same bot token? ps aux | grep -E 'telegram|hermes|openclaw' | grep -v grep shows running gateway processes. If you see two of them, kill the duplicate. The most common scenario is an old OpenClaw gateway still running on the same machine or a Hermes systemd unit plus a manually-started Hermes session in tmux.
Second: have you hit Telegram's per-bot rate limit? Telegram throttles bots that send messages too aggressively (more than ~30 messages per second to the same chat or ~20 messages per minute across all chats). For most personal bots this never matters, but if your agent is sending image-heavy or multi-message responses, you can hit the limit. journalctl -u hermes | grep -i 'too many requests' tells you. Fix by spreading replies out or splitting long replies into one message instead of three.
Third: is the long-poll connection getting silently dropped by something between you and Telegram? VPS providers sometimes have NAT timeouts that kill long-running idle connections. Hermes's default poll cycle accommodates this, but if your network is unusually aggressive about killing idle connections, the connection drop manifests as the bot just not responding to new messages even though the gateway is up. Diagnose by adding HERMES_LOG_LEVEL=debug and watching for connection-lifecycle log lines; if you see "connection reset" entries every few minutes, the network is killing your long polls.
The fix for that last case is to shorten Hermes's long-poll timeout so it reconnects more frequently than your network's idle timeout:
hermes config set messaging.telegram.poll_timeout 30The default is 60 seconds. Drop to 30 if your network is killing connections in the 30-to-60-second window. The trade-off is slightly more bandwidth (more reconnects per minute) and slightly slower reaction to messages that arrive right after a reconnect.
Voice messages and stickers
Telegram messages aren't always text. Voice notes, photos, stickers and files all go through the same gateway. Hermes handles each:
Voice notes: the gateway downloads the OGG, transcribes it via your configured speech-to-text provider (set under tts_stt config) and treats the transcript as the user's message. Configure the STT provider with hermes config set tts_stt.stt_provider whisper (uses OpenAI Whisper) or nous-portal for the Nous-hosted option.
Photos: the gateway downloads the image and sends it to a vision-capable model along with any caption text. Make sure the model you've selected supports vision (most current models do; check hermes model list for "vision" capability tags).
Stickers and GIFs: passed through as image attachments. The agent usually responds with text rather than mirror-stickering you back, which is fine.
Files: the gateway downloads the file and makes it available to the agent under ~/.hermes/inbox/<chat_id>/<filename>. The agent can then read it via filesystem tools. Useful for "summarise this PDF" prompts.
Group chats vs DMs
By default, Hermes responds in DMs. To allow group-chat use, add the bot to a group, then in the group send /start@your_hermes_2026_bot. Telegram fires a chat-membership event the bot picks up.
In groups, the bot only responds when:
The message starts with / followed by a registered command.
The message @-mentions the bot.
The message replies to a previous bot message.
This is by design; otherwise the bot would respond to every message in the group, which is annoying. Tune the trigger conditions with hermes config set messaging.telegram.group_trigger "mentions_only" or similar; the options are documented in the help text.
Multiple Telegram bots from one Hermes instance
One Hermes install can run multiple Telegram bots simultaneously, each with its own token, persona and allowed-users list. The pattern uses Hermes's "channel" abstraction:
hermes config set messaging.telegram.channels '
- name: personal
token: "111:AAA"
allowed_users: [123]
- name: work
token: "222:BBB"
allowed_users: [456, 789]
'Each channel runs as an independent gateway connection but shares the underlying agent. Useful when you want the same agent to be reachable via different bots for different audiences. The agent can tell which channel a message came from and adjust persona accordingly via SOUL.md instructions.
Cross-link to OpenClaw Telegram patterns
If you previously ran Telegram through OpenClaw, our OpenClaw Telegram setup guide covers the equivalent steps for that side; useful if you're migrating settings between the two during the trial period covered in the side-by-side guide.
The shortcut
The LumaDock Hermes Agent VPS template ships Hermes pre-installed on Ubuntu 24.04 with the systemd unit ready and a clean Telegram-config example baked in. Run hermes gateway setup, paste your bot token, you're answering messages in under five minutes.
