Integration
Hermes Agent Telegram Setup and Integration
Connect Hermes Agent to Telegram with BotFather, human user IDs, pairing, fail-closed authorization, groups/topics, gateway proof, and managed hosting.
Quick answer
Use Hermes Agent Telegram when you want a messaging-first agent workflow. Start with one private DM, one profile, one BotFather token, and the human sender's numeric Telegram user ID—or approve a DM pairing code. The token prefix is the bot ID and does not authorize you. Restart the gateway and prove one real reply before adding groups, topics, cron, voice, or multiple agents. Use separate profiles/bots for strict isolation, or FlyHermes when you need managed channel uptime without VPS, Docker, gateway, provider-key, and routing maintenance.
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.
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.
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.
From BotFather token to a working gateway
The Telegram setup is short: create a bot with @BotFather, copy the token, add it to your Hermes config, and restart the gateway. The part people miss is that the gateway has to stay running for messages to flow — confirm the agent answers in the CLI first, because a silent Telegram bot is almost always a provider, config, or gateway-uptime problem rather than a Telegram one.
Watch token usage on Telegram
Reaching Hermes through Telegram costs more tokens than the CLI, because the gateway loads workspace and context files on each turn — community reports put CLI usage around 6–8k input tokens versus roughly 15–20k via Telegram with tools and skills enabled. That's fine for convenience, but it's worth knowing when you budget. For a bot that stays online 24/7 without keeping your own machine running, a managed host like FlyHermes removes the uptime burden.
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.
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.