Hermes Agent Telegram Setup: BotFather, Gateway, Groups, Topics, and Costs
A complete Hermes Agent Telegram setup checklist: BotFather token, active profile, gateway restart, groups, forum topics, provider costs, and FlyHermes managed hosting.
Quick answer
Create a Telegram bot with BotFather, put the token in the exact Hermes profile that runs the gateway, allowlist one user, start or restart the gateway, and test a private DM before groups or forum topics, then prove topic delivery with the exact chat ID plus message_thread_id. Then add group permissions, topic IDs, voice notes, cron delivery, and cost controls one at a time. If you do not want to manage gateway uptime, Docker/VPS restarts, and provider credits, use FlyHermes.
Use this page as the short implementation checklist for Telegram. For why Telegram is useful, start with the Telegram integration overview; for deeper debugging and hosting trade-offs, use the full Telegram setup article.
Managed cloud · API costs included · Skill library · Cancel anytime
Before you start:
- ☑Hermes Agent installed and running
- ☑A Telegram account
- ☑Your Telegram user ID (get it from @userinfobot on Telegram)
- ☑If you updated to v0.16, verify Telegram from the dashboard/admin surface and then send a real message in the exact chat or topic
Steps
- 1
Create a Telegram bot in BotFather
Message @BotFather, run /newbot, name the bot, and copy the token once. Treat it like a secret.
- 2
Put the token in the active Hermes profile
Use hermes config env-path or the gateway setup wizard for the profile that will actually run Telegram. Profiles isolate tokens, memory, skills, and sessions.
- 3
Allowlist your first user or chat
Start with one Telegram user ID or DM. Do not begin with a large group until the private smoke test passes.
- 4
Start or restart the gateway
Run hermes gateway setup and hermes gateway restart/start so the long-running gateway process reads the new token and allowlist.
- 5
Verify a private DM
Send one short message to the bot and confirm the response uses the expected model/profile before adding voice notes or files.
- 6
Add groups and forum topics carefully
For groups, decide mention-only vs free-response behavior. For forum topics, verify message_thread_id/topic routing and permissions with a real message.
- 7
Control provider costs
Telegram conversations can include longer context, voice transcription, cron reports, and group noise. Set model/provider routes intentionally and monitor usage.
- 8
Choose FlyHermes if uptime is the goal
Use FlyHermes when you want Telegram/mobile access with managed hosting and connected channels rather than maintaining a VPS, Docker, launchd/systemd, and provider fallback stack.
- 9
Prove forum-topic routing with the exact thread ID
For Telegram forum topics, verify the bot receives the update in gateway logs, then configure the exact chat_id plus message_thread_id for free-response or cron delivery. A normal group test is not enough.
Pro Tips
- 💡Keep the first bot private and allowlist only your Telegram user ID.
- 💡Use mention-only behavior before adding Hermes to groups.
- 💡Recent Reddit searches around multiple Telegram bots and unreachable Telegram/dashboard setups show the real commercial question: can this stay online without you babysitting the VPS?
- 💡For always-on Telegram, compare VPS/self-hosting with FlyHermes instead of relying on a laptop process.
- 💡Use the Hermes Web UI as a private status checkpoint; if you enable --tui, remember it is local browser TUI access, not proof that the Telegram gateway can deliver messages.
- 💡If the real goal is dashboard visibility, Telegram/Discord uptime, or browser/mobile access without VPS upkeep, compare FlyHermes before expanding self-hosted infrastructure.
- 💡Use the Hermes dashboard/Web UI as a status checkpoint, but verify success with the real command, channel message, cron delivery, or deployed URL that matters.
- 💡After the bot replies once, open the private Hermes dashboard and confirm the active profile, gateway status, provider, and cron jobs; then send a second message in the exact DM/group/topic before declaring Telegram healthy.
Troubleshooting
❌ BotFather token works locally but not in the gateway
✅ Check the active Hermes profile and service environment. The CLI may read a different .env/config than the launchd/systemd/Docker gateway.
❌ Bot replies in DMs but not groups
✅ Verify group chat IDs, bot permissions, mention requirements, privacy settings, and allowed_chats/free_response_chats configuration.
❌ Forum topic does not respond
✅ Test the bot in the parent group, then verify the topic message_thread_id and topic-specific routing. A plain chat_id test does not prove forum-topic delivery.
❌ Telegram costs more than expected
✅ Check loaded skills, project instructions, voice transcription, cron jobs, and provider fallback/auxiliary model routes.
❌ Gateway looks connected but Telegram is silent
✅ Hard-restart the gateway process, inspect agent logs, and send a real DM. Do not rely only on a stale connected status file.
❌ Telegram forum topic stays silent but DMs work
✅ Check BotFather privacy, can_read_all_group_messages, group allowlist, topic message_thread_id, gateway logs for inbound updates, and whether require_mention blocks free response in that topic.
FAQ
Do I need BotFather for Hermes Agent Telegram?
Yes. BotFather creates the Telegram bot token that the Hermes gateway uses. Store it only in the active Hermes profile or secret environment.
Can Hermes Agent work in Telegram groups and topics?
Yes. Test a DM first, then add groups with clear mention/free-response rules and verify forum topic thread IDs with real messages.
Does Telegram make Hermes Agent more expensive?
It can. Longer chat context, voice transcription, cron reports, group messages, and auxiliary model calls can all add provider usage. Use provider routes and cost monitoring intentionally.
When should I use FlyHermes instead?
Use FlyHermes when you want managed Telegram/mobile access, hosted uptime, connected channels, and fewer VPS/Docker/provider-key chores.
Why is Hermes Agent not replying in a Telegram forum topic?
Most topic failures are routing or permission problems, not model failures. Verify the bot can read group messages, the group is allowlisted, the exact topic message_thread_id is configured for free response or cron delivery, and the gateway logs show the inbound update before testing provider fallbacks.