How-To Guide
How to Connect Telegram to Hermes Agent
Connect Telegram to Hermes Agent with QR or BotFather. Check the active profile, authorize your human ID, test a private reply, then add groups safely.
Quick answer
Choose the owning Hermes profile, use Create with QR or the manual BotFather setup, authorize your human account, and test a harmless private message. Only then install or verify the gateway service and add the exact group or topic you need.
Use this checklist to connect one bot and prove it replies. Start with the Telegram overview for access and hosting choices or the detailed setup guide for commands and offline-message recovery.
$49/mo or $39/mo billed yearly · AI included · 14‑day guarantee
Before you start:
- ☑A working Hermes installation and model provider
- ☑A Telegram account and access to the account that runs the gateway
- ☑The intended profile and an always-on host if the bot must answer while your computer is off
Steps
- 1
Confirm the owning profile
Run
hermes config path,hermes config env-pathandhermes gateway statusfrom the service account. Add-p PROFILEfor an existing named profile. Do not print the secret file. The profiles guide explains configuration boundaries; profiles alone are not a host filesystem sandbox. - 2
Choose QR or manual bot creation
In current dashboard or Desktop builds, open Messaging → Telegram → Create with QR. Hermes creates the bot, detects your user ID, writes the selected profile settings and restarts the gateway. For manual setup, use @BotFather /newbot and then
hermes gateway setup. Follow the official Telegram documentation for the version you run. - 3
Authorize the human, not the bot
Use your numeric human ID from @userinfobot or @get_id_bot in TELEGRAM_ALLOWED_USERS. The token prefix is the bot ID. Alternatively inspect
hermes pairing listand approve only the intended DM sender withhermes pairing approve telegram <code>. Keep real tokens and codes out of public support posts. - 4
Test one private reply
For a first manual foreground test run
hermes gateway run. Send “Reply with TELEGRAM-CHECK-1 only. Do not run tools or change anything.” Verify that exact reply in the same DM. For QR setup with an already running gateway, test that instance rather than starting a second poller. - 5
Verify the service without competing pollers
Stop a foreground test before using the same token in a service. On supported native hosts use
hermes gateway install,hermes gateway startandhermes gateway status, then send a new harmless marker. For an existing service after configuration changes usehermes gateway restart. Use the gateway recovery guide if the real reply fails. - 6
Choose offline-message behavior
Current Telegram docs, checked November 19, 2026, preserve the cold-boot backlog by default with
platforms.telegram.extra.drop_pending_on_cold_boot: false. An explicittruediscards it. Confirm the installed version and chosen policy; old instructions may execute at startup. Test harmless offline and online markers during an idle maintenance window using the detailed queue acceptance check. Watcher reconnects and conflict recovery preserve the queue; this is not exactly-once execution. - 7
Add only the group or topic you need
Authorize selected group senders with TELEGRAM_GROUP_ALLOWED_USERS or all members of named groups with TELEGRAM_GROUP_ALLOWED_CHATS. Check BotFather privacy and mention rules separately; remove and re-add the bot after privacy changes. Enable Threads and use /topic for parallel DM sessions. Verify the exact chat and message_thread_id rather than assuming a parent-group reply proves topic delivery.
- 8
Verify optional files and scheduled results
A generated attachment needs a MEDIA path readable by the sending gateway, not only a Docker tool sandbox. For scheduled output, pin the destination and TELEGRAM_CRON_THREAD_ID where applicable, then verify a harmless manual result using the cron delivery guide. Neither a connected status nor a successful scheduler run proves delivery.
Pro Tips
- 💡Use the private WebUI for status and logs; its PTY/WebSocket browser Chat is separate from Telegram delivery.
- 💡Use polling on an always-on host without opening a public inbound port. Webhook mode needs HTTPS and TELEGRAM_WEBHOOK_SECRET.
- 💡Keep optional unmentioned-group observation limited to trusted chats; stored context, voice and long sessions can increase provider usage.
- 💡Compare managed hosting when runtime upkeep is the burden you want to remove. Verify current plan/channel support; self-hosted browser Chat already exists.
Troubleshooting
❌ Connected, but no private reply
✅ Trace one fresh harmless message through receipt, authorization, provider completion and Telegram sending. Check the correct bot and owning profile; do not hard-restart an active task or rotate a valid token without evidence.
❌ Blocked unauthorized user
✅ Use the human sender ID or an approved pairing record. Do not use the bot-token prefix, chat ID or topic ID in TELEGRAM_ALLOWED_USERS.
❌ Only old offline messages are missing
✅ Check your installed version, the explicit cold-boot policy and the outage duration: Telegram retention is no longer than 24 hours. Current docs preserve the queue by default; true opts into discarding it. A fresh online reply tests a different path from backlog handling. Inspect prior external results before resending an old consequential instruction.
❌ DM works but the forum topic does not
✅ Inspect the inbound update, group authorization, privacy/mention rules and the exact thread. Test that destination, not just the parent group.
❌ Recovered response is labeled a possible duplicate
✅ The earlier send may already have reached Telegram. Check any external action before repeating it; reply recovery and exactly-once execution are different promises.
❌ A file exists in Docker but will not attach
✅ Use a narrow shared task mount and the matching gateway-readable path. Do not mount all Hermes secrets to fix an attachment.
FAQ
Do I need to use BotFather manually?
Not in current dashboard or Desktop builds with Create with QR. Manual BotFather creation remains supported through hermes gateway setup.
What is the minimum successful test?
One authorized human sends a harmless unique marker and sees the expected reply in the same private DM. Repeat after service startup; test groups, topics and files separately if you use them.
Does a connected gateway prove Telegram works?
No. Receipt, authorization, inference and final sending can fail separately. Inspect one new harmless message end to end.
Will messages sent while my laptop is off run later?
Current docs preserve the backlog by default with drop_pending_on_cold_boot: false. An explicit true value discards it on cold boot. Check the installed version and policy; old instructions can execute when the gateway starts. Telegram retention is no longer than 24 hours.
Do separate topics protect secrets from other users?
Topics separate conversation sessions, not filesystem or tool access. Use separate profiles and appropriate runtime isolation for stronger trust boundaries.
Can I use browser Chat without managed hosting?
Yes. Self-hosted WebUI supports PTY/WebSocket Chat. Managed hosting changes who maintains the runtime rather than whether browser Chat exists.