How-To Guide
How to Connect Telegram to Hermes Agent
Step-by-step Telegram setup for Hermes Agent: BotFather token, profile isolation, gateway restart, DM smoke test, groups/topics, and FlyHermes hosted path.
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. For forum topics, prove delivery with the exact chat ID plus message_thread_id. For multiple projects or agents, prefer separate Hermes profiles and usually separate Telegram bots. If you do not want to manage gateway uptime, Docker/VPS restarts, provider credits, topic routing, and bot-token operations, 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
Choose one bot or separate profile/bot boundaries
Use one bot for a private personal workflow. Use separate Hermes profiles, and often separate bot tokens, when different projects need different secrets, memory, skills, filesystem access, or trust boundaries.
- 4
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.
- 5
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.
- 6
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.
- 7
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.
- 8
Control provider costs
Telegram conversations can include longer context, voice transcription, cron reports, and group noise. Set model/provider routes intentionally and monitor usage.
- 9
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.
- 10
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.
- 11
Run a Telegram operations checklist before calling it done
After the first reply, verify dashboard/gateway status, active provider, allowed chats, group privacy, topic thread ID, logs, cron delivery target if used, and provider-cost guardrails. A connected gateway status is not the same as a successful message in the target chat.
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.
- 💡Weekly buyer-demand note (2026-06-22): recent GSC/dashboard searches, Reddit Claude Code monitor/cost threads, YouTube dashboard walkthroughs, and Discord gateway/support clusters all point to the same decision — self-host if you want control, but use FlyHermes when dashboard visibility, Telegram/Discord uptime, provider credits, and VPS maintenance are the work you do not want to own.
- 💡June 2026 source evidence: Telegram Hermes setup demand is “from scratch” operations work — install, provider/model choice, BotFather, gateway process, group/topic routing, and uptime all appear in fresh YouTube/Reddit evidence.
- 💡If one Telegram bot starts serving unrelated projects, split the setup into separate Hermes profiles and bot tokens before secrets, memory, or file access blur together.
- 💡Use the Telegram guide together with the VPS, Docker, Web UI, provider-cost, and hosted-vs-self-hosted pages so readers can choose the smallest reliable operating model.
- 💡Before declaring the workflow fixed, open the private Hermes dashboard, select the correct profile, check provider/model/gateway/cron state, and then verify the real channel or scheduled delivery path.
- 💡If the Telegram bot is part of a Claude Code alternative workflow, decide whether you want self-hosted gateway maintenance or FlyHermes managed channel uptime before adding more projects to one bot.
- 💡Use the Hermes Web UI as the checkpoint for provider, profile, cron, and gateway state, then prove the integration with one real Telegram reply in the exact target channel or topic.
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.
❌ One Telegram bot is serving too many workflows
✅ Create separate Hermes profiles first; if the workflows have different users, secrets, skills, memory, or trust boundaries, create separate Telegram bots too. Do not rely on prompt instructions alone for real isolation.
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.
Can one Telegram bot serve multiple Hermes profiles?
For a simple personal setup, one bot can be enough. For separate clients, projects, trust levels, or skill/secret sets, use separate profiles and usually separate bot tokens so Telegram routing matches Hermes isolation.