How-To Guide
How to Connect Telegram to Hermes Agent
Connect Hermes Agent to Telegram: BotFather, secure user/chat allowlists, group privacy, DM topics, cron thread routing, polling or webhooks, and delivery proof.
Quick answer
Create a BotFather bot, store its token in the exact Hermes profile that runs the gateway, authorize your human Telegram ID, and prove one private reply. For groups, separate sender allowlists from allowed chat IDs and verify BotFather privacy. Use /topic for parallel DM sessions, TELEGRAM_CRON_THREAD_ID for scheduled delivery, polling for always-on hosts, or a signed webhook for sleep-capable clouds.
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
Find your human numeric Telegram user ID with @userinfobot or @get_id_bot and add that value to TELEGRAM_ALLOWED_USERS. Do not use the numeric prefix from the BotFather token: that is the bot ID, not your account ID.
- 5
Use pairing when you do not want to copy IDs manually
Let the unknown user DM the bot, inspect the pending code with
hermes pairing list, and approve it withhermes pairing approve telegram <code>. In the official Docker image, run the approval withdocker exec -u hermes ...so the gateway can read the protected pairing file. - 6
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.
- 7
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.
- 8
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.
- 9
Control provider costs
Telegram conversations can include longer context, voice transcription, cron reports, and group noise. Set model/provider routes intentionally and monitor usage.
- 10
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.
- 11
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.
- 12
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.
- 13
Separate group users from group chats
Put selected human senders in TELEGRAM_GROUP_ALLOWED_USERS and whole negative group IDs in TELEGRAM_GROUP_ALLOWED_CHATS. These are different scopes; BotFather privacy and mention rules still apply.
- 14
Create parallel DM sessions when needed
Enable Threads for the bot and run /topic in the root DM. Each Telegram topic gets its own Hermes session and context; use a separate profile when secrets or tool access must also be isolated.
- 15
Pin cron output to a real topic
Set TELEGRAM_CRON_THREAD_ID for topic-enabled DMs, trigger one job manually, and confirm the result appears in that exact topic rather than the system lobby.
- 16
Choose polling or signed webhooks
Keep default polling on an always-on host. For cloud wake-on-message, configure TELEGRAM_WEBHOOK_URL plus the required TELEGRAM_WEBHOOK_SECRET and verify the HTTPS endpoint.
- 17
Test restart recovery safely
Hermes can redeliver unfinished responses from its delivery ledger after restart. Treat delivery as at-least-once and keep external side effects idempotent.
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.
- 💡After changing BotFather group privacy, remove and re-add the bot so Telegram refreshes its cached delivery rules.
- 💡Use observe_unmentioned_group_messages only in trusted allowlisted chats; observed text becomes context even when it does not trigger a reply.
- 💡A Telegram Online short-description indicator is only a hint: hard crashes can leave it stale, so verify logs and a real round trip.
- 💡For Docker tools, write attachments to a shared mount and emit a MEDIA path the host gateway can read.
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.
❌ Telegram says blocked unauthorized user
✅ The token prefix identifies the bot, not the human sender. Find your own user ID with @userinfobot or @get_id_bot, put it in TELEGRAM_ALLOWED_USERS or approve a pairing code, restart the correct profile's gateway, and send a new DM.
❌ 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.
❌ Bot receives mentions but not ordinary group messages
✅ Check BotFather privacy or admin status. If privacy was changed, remove and re-add the bot, then inspect logs for the exact group update.
❌ Cron result lands in the Telegram root lobby
✅ Set TELEGRAM_CRON_THREAD_ID to a real DM topic and verify one manual job. The root of a topic-enabled DM is reserved for system commands.
❌ Recovered reply may be duplicated after restart
✅ This is honest at-least-once delivery. Hermes labels ambiguous recovered sends; reconcile consequential external actions before retrying them.
❌ Telegram cannot send a file created in Docker
✅ The gateway needs a host-readable MEDIA path. Add one shared volume, write the file there, and emit the matching host path.
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.
Which Telegram ID belongs in TELEGRAM_ALLOWED_USERS?
Use the numeric ID of the human Telegram account sending messages. Do not use the bot ID from the token prefix, a group chat ID, or a forum topic ID. You can also authorize a DM user through Hermes pairing.
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.
Can I run separate Hermes sessions inside one Telegram DM?
Yes. Enable Telegram Threads and use /topic. Every topic maps to its own Hermes session; profiles remain the stronger isolation boundary for secrets, tools, and files.
Should Telegram use polling or a webhook?
Use polling on an always-on Mac, server, or VPS. Use webhook mode for a cloud host that should wake on inbound HTTPS, and always configure TELEGRAM_WEBHOOK_SECRET.
Does Telegram delivery survive a Hermes gateway restart?
The delivery ledger can recover unfinished replies, but semantics are at-least-once. Ambiguous recovered sends are labeled as possible duplicates.