Integration
Hermes Agent Telegram Setup, Topics, and Reliable Delivery
Connect Hermes Agent to Telegram with secure user/chat allowlists, groups, DM topics, cron routing, polling or webhooks, restart recovery, and managed hosting.
Quick answer
Start with a BotFather token, one authorized human user, and one verified DM. Then choose group sender/chat allowlists, mention/privacy behavior, DM topic isolation, and an exact cron thread. Polling is simplest for an always-on machine; signed webhooks suit sleep-capable cloud hosts. Hermes can recover unfinished replies from its delivery ledger, but delivery remains at-least-once. Use FlyHermes when you want the channel outcome without owning gateway uptime and routing.
Managed cloud · API costs included · No gateway maintenance
Best for
Private mobile access to a local or VPS-hosted Hermes Agent
Cron/job alerts sent to a chat you already check
Voice-note and file handoffs when you are away from the terminal
Small trusted groups where Hermes only responds when mentioned
Features
- ✓BotFather token setup for a dedicated Hermes bot
- ✓Allowed users, allowed chats, groups, and forum topic/thread routing
- ✓Gateway start/restart/status checks before production use
- ✓Provider-cost controls for Telegram sessions, voice notes, cron reports, and group messages
- ✓FlyHermes managed cloud option when uptime and mobile access matter more than self-hosting
- ✓Telegram gateway setup with one private smoke test first
- ✓Messaging workflow checks before groups or production automation
- ✓Credential and profile boundaries for safer bot access
- ✓Fail-closed authorization with human user IDs or one-time DM pairing codes—not the bot-token prefix
- ✓v0.16 dashboard/admin checks before rotating Telegram bot tokens
- ✓Weekly conversion update (2026-06-22): position this integration as an always-on channel workflow; if the buyer does not want gateway logs, provider fallbacks, VPS restarts, and dashboard maintenance, route them to FlyHermes.
- ✓Claude Code alternative handoff: use Telegram when coding-agent output needs phone/team delivery rather than another terminal tab
- ✓Web UI checkpoint before token churn: verify profile, provider, gateway, cron, and logs before rotating bot credentials
- ✓Web UI is the checkpoint; one delivered Telegram message is the proof. Use the dashboard to inspect profile, provider, gateway, logs, and cron state before rotating bot tokens.
- ✓Separate human sender authorization from whole-group chat authorization
- ✓Private DM topics with one isolated Hermes session per Telegram thread
- ✓Exact cron-topic delivery with TELEGRAM_CRON_THREAD_ID
- ✓Polling for always-on hosts or signed webhook mode for sleep-capable clouds
- ✓Restart-safe delivery ledger with visible possible-duplicate labeling
- ✓Optional group observation without unsolicited agent replies
- ✓Optional bot-profile status indicator with honest stale-state limits
- ✓Host-visible MEDIA paths for Docker-generated Telegram attachments
- ✓Discord and Telegram share the same proof rule: connected is only a checkpoint. Verify one inbound event, one completed agent turn, and one reply in the exact destination.
Setup path
- 1Create a bot in @BotFather and save the token once in the active Hermes profile, not in a random shell or committed file.
- 2Start with a private DM and allowlist the human Telegram user ID from @userinfobot/@get_id_bot; the numeric prefix in the BotFather token identifies the bot, not the sender.
- 3Alternatively approve the DM pairing code with
hermes pairing approve telegram <code>; Docker users should execute the command as thehermesuser. - 4Run hermes gateway setup or configure the Telegram gateway, then restart the gateway process so token/chat changes load.
- 5For groups, decide whether Hermes should require mentions, respond freely in selected chats, or respond only in specific forum topics.
- 6Watch provider usage: Telegram voice notes, long group context, loaded skills, and cron reports can cost more than a short CLI prompt.
- 7Use FlyHermes if you want Telegram/mobile access with managed hosting, connected channels, and bundled operations instead of maintaining a VPS or Docker service.
- 8For groups, put human IDs in TELEGRAM_GROUP_ALLOWED_USERS and negative group IDs in TELEGRAM_GROUP_ALLOWED_CHATS; these are different authorization scopes.
- 9If BotFather privacy changes, remove and re-add the bot; Telegram can cache the old group-delivery setting.
- 10For parallel DM work, enable Threads and use /topic so each Telegram topic maps to its own Hermes session.
- 11Pin scheduled output to a real topic with TELEGRAM_CRON_THREAD_ID and verify one manual run in that exact destination.
- 12Use long polling on always-on hosts; use webhook mode only with a public HTTPS URL and TELEGRAM_WEBHOOK_SECRET.
Telegram authorization: bot identity versus human identity
A valid BotFather token only proves which bot the gateway controls. Hermes separately authorizes the human who sends a message, and denies access when no allowlist or pairing approval matches.
- •Bot token prefix: bot account ID; keep the full token secret.
- •TELEGRAM_ALLOWED_USERS: positive numeric human account IDs.
- •Group/supergroup IDs: negative chat IDs used for chat-scoped access.
- •Forum topics: message_thread_id values tested inside the exact group or DM topic.
Telegram setup path
The safe setup pattern for Hermes Telegram is narrow first, then expansion. Prove one reply in a private conversation, check gateway logs, and only then add groups, media, cron jobs, or team workflows.
- •Use the active Hermes profile intentionally
- •Verify one message end to end
- •Keep tokens out of prompts and committed files
- •Document the working setup as a reusable skill when it becomes repeatable
Telegram deployment decision tree
The most common mistake is treating “Telegram bot” as one setup. Choose the operating model first, then configure Hermes around that boundary.
- •One user / one bot / local Mac: fastest path for private mobile access; keep allowed_chats narrow and verify one DM.
- •One group or forum topic: add the group only after the DM works; verify mention rules, privacy mode, and message_thread_id with a real topic message.
- •Multiple projects or agents: create separate Hermes profiles and usually separate bot tokens so secrets, memory, skills, sessions, and filesystem access do not bleed between projects.
- •Team or always-on channel: use VPS/Docker only if you want to own uptime, logs, restarts, provider credits, and gateway upgrades; use FlyHermes when the business need is hosted Telegram/mobile access without that operations layer.
Safe Telegram rollout path
Start with one private chat and one Hermes profile. After the first smoke test, add voice notes, cron delivery, or group access one at a time so token overhead and permission mistakes stay visible.
- •Private chat first: token, allowed user ID, one smoke-test message.
- •Group/topic second: require mentions and verify the group or topic ID.
- •Always-on third: move to VPS, Docker Compose, or FlyHermes only after local behavior is correct.
Community evidence to include in the setup
Discord support history repeatedly surfaced messaging-gateway issues: Telegram token overhead from a bad startup directory, gateway restart questions, and platform bots reading more context than expected. The practical fix is to treat the gateway as production infrastructure, not a casual chat plugin.
- •Run Hermes from the intended home/project directory.
- •Keep gateway profiles smaller than your full local coding profile.
- •Check logs after every token, allowlist, or group-setting change.
Fresh demand signal: Telegram setup is really operations work
The June 2026 content-intelligence refresh found fresh YouTube and Reddit evidence that people want end-to-end Telegram agent setup, not just a token field. Tutorials emphasize installing Hermes from scratch, choosing a model provider, creating a BotFather bot, and then keeping the gateway alive.
- •YouTube setup videos frame Telegram as a complete from-scratch workflow: install → provider/model → BotFather → gateway → test.
- •Reddit Hermes/profile discussions ask whether one Telegram bot can serve multiple agents and when Docker, VMs, or separate machines are needed for isolation.
- •Historical Discord support data still shows Telegram/Discord/gateway and install/Docker/provider-cost issues clustering together; use it as stale but useful support-demand evidence.
People and chats are separate authorization scopes
Authorize individual humans with allowed-user fields and whole groups with allowed-chat fields. BotFather privacy and Hermes mention rules are additional delivery gates.
- •Positive IDs identify users
- •Negative -100 IDs identify supergroups
- •message_thread_id identifies one topic
- •A valid bot token authorizes the bot, not the human sender
One Telegram DM can hold parallel Hermes sessions
Enable Threads and use /topic for user-created workspaces, or configure fixed DM topics with optional skill bindings. Each topic keeps its own session and context.
- •Use /new to reset one topic
- •Use /topic <session-id> to restore an older session
- •Use separate profiles for stronger secret and tool isolation
Delivery has a real operating model
Polling is simplest on an always-on host. Signed webhook mode enables cloud wake-on-message. The delivery ledger recovers unfinished responses after restarts with at-least-once semantics.
- •Verify the exact DM/group/topic
- •Expect possible-duplicate labels after ambiguous sends
- •Make consequential side effects idempotent
From BotFather token to a working gateway
A token identifies the bot; a user/chat allowlist authorizes who can reach the agent. Prove the provider in the CLI, the gateway process, and one real Telegram reply as three separate checks.
Topics, schedules, and restart recovery
DM and forum topics isolate sessions, TELEGRAM_CRON_THREAD_ID pins scheduled delivery, and the gateway delivery ledger recovers unfinished responses. None of these replaces an end-to-end message test in the exact target.
Common setup issues
- Blocked unauthorized user: replace the bot-token prefix with the human sender ID in TELEGRAM_ALLOWED_USERS, or approve the sender's pairing code, then restart the correct profile's gateway.
- Bot does not answer in DM: verify the token, allowed user ID, active profile, gateway process, and logs.
- Group works but topic does not: verify message_thread_id/topic mapping and whether the bot is allowed to read/post in that forum topic.
- Costs spike after moving to Telegram: check loaded project context, skills, voice transcription, cron jobs, and auxiliary provider routes.
- Gateway says connected but no reply arrives: restart the service process, not just the chat session, and test with a fresh DM.
- If setup feels like infrastructure work, choose FlyHermes so the hosted path owns uptime and channel operations.
- Dashboard says connected but Telegram is silent: use Web UI to check active profile/provider/gateway state, then verify BotFather token, allowed chats, privacy/mention settings, topic ID, logs, and one real message in the exact chat.
- Use the Hermes dashboard to inspect gateway logs and provider state, then verify one real Telegram send/reply in the exact target channel before calling the integration healthy.
- Choose FlyHermes when the blocker is always-on channel uptime, provider plumbing, or server restarts rather than a one-time bot-token setup.
- Bot sees mentions but not ordinary group messages: check BotFather privacy, admin status, and whether the bot was removed/re-added after the setting changed.
- Cron lands in the DM lobby: set TELEGRAM_CRON_THREAD_ID to a real topic; the root of a topic-enabled DM is reserved for system commands.
- A reply appears twice after restart: the delivery ledger is at-least-once and visibly labels ambiguous recovery; make downstream side effects idempotent.
- Docker-created attachment is missing: the MEDIA path must be readable by the host gateway, not only inside the terminal container.
FAQ
Is Telegram better than Discord for Hermes Agent?
Telegram is better for private mobile access, voice notes, quick approvals, and alerts. Discord is better for team/community channels, slash commands, and threaded collaboration.
Can Hermes Agent use Telegram groups and topics?
Yes, but verify private messages first, then add groups or topics with allowlisted users and mention-only behavior so Hermes does not free-respond in the wrong place.
Why does Telegram sometimes use more tokens than the CLI?
Gateway sessions can load different working-directory instructions, skills, or profile context than the CLI. Check the gateway working directory, active profile, and loaded context before changing models.
Why does Hermes block me as an unauthorized Telegram user?
Hermes needs the human sender's numeric Telegram user ID, not the bot ID at the start of the BotFather token. Add the human ID to TELEGRAM_ALLOWED_USERS or approve the one-time DM pairing code, then restart and retest the correct profile.
Where do I find the setup steps?
Use the connect Telegram checklist for short steps or the Telegram setup blog post for deeper hosting, group, and troubleshooting guidance.
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.
How do I connect Hermes Agent to Telegram?
Configure the Telegram gateway in the active Hermes profile, run one private smoke test, check gateway logs, then add groups or automation only after the first reply is verified.
Can Hermes Agent run scheduled jobs through Telegram?
Yes. Use Hermes cron for scheduled work and deliver the result to the Telegram channel only after the gateway is verified with a direct test message.
Can one Telegram bot serve multiple Hermes agents?
You can route multiple conversations through one bot in simple cases, but strict project isolation should use separate Hermes profiles and often separate Telegram bot tokens. Profiles isolate memory, skills, sessions, secrets, and gateway state; separate bots make chat boundaries clearer for teams.
Should I self-host Telegram or use FlyHermes?
Self-host when you want control over the Hermes gateway, profiles, server, logs, and provider keys. Use FlyHermes when the goal is managed Telegram/mobile access and always-on uptime without maintaining a laptop, VPS, Docker stack, BotFather routing, or provider-credit plumbing.
How does Telegram fit a Claude Code alternative workflow?
Telegram is the delivery layer when the agent work should reach a phone, team channel, support thread, or scheduled report instead of staying inside a terminal. Use Hermes Web UI to inspect gateway health, then verify a real Telegram reply.
Can Telegram topics keep Hermes conversations separate?
Yes. User-driven /topic mode and configured DM/group topics map each thread to an isolated Hermes session. Use profiles too when secrets, tools, or filesystem access need stronger separation.
Does Hermes Telegram need a public port?
Not in default polling mode. A public HTTPS endpoint is needed only for webhook mode, which also requires TELEGRAM_WEBHOOK_SECRET.
Why did a Telegram reply repeat after a gateway restart?
Hermes uses honest at-least-once recovery. If the prior send may have started, the recovered reply is labeled as a possible duplicate rather than silently assuming it was lost.