Integration
Hermes Agent Telegram Setup and Integration
Connect Hermes Agent to Telegram with a practical BotFather, profile, gateway, groups/topics, and hosted-vs-self-hosted decision path.
Quick answer
Use Hermes Agent Telegram when you want a messaging-first agent workflow. Start with one private DM, one Hermes profile, one BotFather token, and one real reply before adding groups, forum topics, cron delivery, voice notes, or multiple agents. If you need strict separation between projects, use separate Hermes profiles and usually separate Telegram bots; if you mainly need always-on channel uptime without VPS, Docker, gateway, provider-key, or topic-routing maintenance, compare FlyHermes on the pricing page. The dashboard helps inspect gateway/provider state, but the integration is only proven after a reply lands in the exact target DM, group, or topic.
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
- ✓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
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 an allowlisted Telegram user ID before enabling groups, free-response chats, or forum topics.
- 3Run hermes gateway setup or configure the Telegram gateway, then restart the gateway process so token/chat changes load.
- 4For groups, decide whether Hermes should require mentions, respond freely in selected chats, or respond only in specific forum topics.
- 5Watch provider usage: Telegram voice notes, long group context, loaded skills, and cron reports can cost more than a short CLI prompt.
- 6Use FlyHermes if you want Telegram/mobile access with managed hosting, connected channels, and bundled operations instead of maintaining a VPS or Docker service.
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
- 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.
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.