Hermes Agent Telegram Setup: BotFather, Gateway, Groups, Topics, and Costs

This page is the focused setup guide for connecting Hermes Agent to Telegram. It complements the Telegram integration overview, the short Telegram checklist, and the Hermes Web UI dashboard you can use to monitor the gateway after it is running.

Why Telegram setup deserves its own guide#

Telegram looks simple because the first step is just a BotFather token. The real production setup has more moving parts:

• the active Hermes profile that owns the token, tools, memory, and skills
• the long-running gateway process, not just an interactive CLI session
• allowed users, allowed chats, groups, and forum topics
• provider routes, rate limits, voice transcription, and cron delivery costs
• uptime through a laptop, VPS, Docker Compose, launchd, systemd, or FlyHermes

Recent Discord support data shows messaging-platform issues as a major recurring cluster, with adjacent provider/cost and install/update/gateway restart issues. Treat Telegram like a production gateway, not like a casual chat plugin.

Step 1: Create the bot in BotFather#

Open Telegram and message @BotFather:

/newbot
Hermes Ops Bot
hermes_ops_example_bot

Copy the token once and store it as a secret. Do not paste it into screenshots, public GitHub issues, Docker examples, or prompts.

Step 2: Put the token in the active Hermes profile#

Before editing secrets, confirm which profile will run Telegram:

hermes profile list
hermes config path
hermes config env-path

If you run a dedicated Telegram bot, prefer a dedicated Hermes profile so Telegram memory, skills, provider keys, and allowed chats stay scoped. The same principle matters for persistent memory and local Obsidian notes: scope the surface before you expand access.

Step 3: Allowlist a private DM first#

Start with one Telegram user ID and one private message test. A DM test proves the token, active profile, provider route, and gateway process are all reading the same configuration.

Only after the DM works should you enable:

• group chats
• forum topics
• free-response threads
• voice messages
• cron-job delivery
• file uploads

This sequence keeps permission mistakes and cost surprises small.

Step 4: Start or restart the gateway#

Use the setup wizard or config path that matches your install:

hermes gateway setup
hermes gateway restart
hermes gateway status

If the gateway is a macOS launchd service, Docker service, VPS process, or tmux session, remember that /reset only refreshes the conversation. It does not necessarily restart the Python gateway process that reads tokens and platform config. For service-level problems, use the install and update troubleshooting guide.

Step 5: Add groups and topics carefully#

Groups and Telegram forum topics require more than a valid chat_id. Decide whether Hermes should respond only when mentioned or freely in selected chats. For forum topics, verify the message_thread_id with a real topic message; a plain group send test does not prove topic routing.

A safe rollout pattern is:

1. DM smoke test.
2. One private group with mention-required behavior.
3. One forum topic with explicit topic/thread routing.
4. Cron delivery to that exact chat/topic.
5. Broader group access only after logs are clean.

Step 6: Control provider costs and fallbacks#

Telegram usage can cost more than short CLI prompts because gateway sessions may load additional instructions, skills, long chat context, voice transcription, or scheduled reports. Pair this setup with the model provider cost guide and the provider fallback guide.

Cost controls to check:

• main model/provider for Telegram sessions
• auxiliary routes for compression, session search, memory, or delegation
• voice transcription provider if voice notes are enabled
• cron job frequency and delivery targets
• group/free-response scope

Self-hosted Telegram vs FlyHermes#

Self-hosting is the right path if you want full control of the machine, profile, secrets, plugins, and gateway service. FlyHermes is the simpler path if the outcome is “Hermes in Telegram/mobile/channels with managed uptime.”

Choose self-hosted when you want:

• local/VPS control
• custom tools and profiles
• your own provider keys
• private infrastructure decisions

Choose FlyHermes when you want:

• hosted cloud access
• mobile/chat convenience
• connected channels without service maintenance
• API costs bundled into the commercial path
• less Docker, launchd/systemd, provider, and gateway debugging

Forum topics not replying: the proof path#

Telegram forum topics add one more routing layer on top of normal group setup. A private DM can work while a topic stays silent if Hermes never receives the topic update, the bot cannot read all group messages, the group is not allowlisted, or the topic is missing its message_thread_id in the delivery/free-response rule.

Use this order before changing models:

1. Prove the bot receives updates in the group: check gateway logs for the group chat_id and topic message_thread_id.
2. Confirm BotFather privacy is off for group/topic work, or mention the bot explicitly if privacy stays on.
3. Verify the Hermes Telegram config uses the supergroup chat_id and the topic message_thread_id; private t.me/c links do not show the thread ID directly.
4. Test a manual message in the exact topic, then test a cron delivery to the same topic.
5. Only after the inbound update appears in logs should you debug providers, memory, or prompt routing.

If you do not want to own this routing stack, FlyHermes is the managed path for using Hermes from your phone without maintaining Telegram gateway uptime yourself.

FAQ#

Do I need BotFather for Hermes Agent Telegram?#

Yes. BotFather creates the 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 fallback settings intentionally.

If your real goal is an always-on phone agent rather than a one-off bot test, read the Hermes 24/7 AI agent setup guide after this Telegram setup so provider limits, VPS uptime, cron delivery, and dashboard checks are not missed.

If Telegram suddenly stops replying#

After setup works once, the most common recovery path is not a new token. Run the gateway troubleshooting checklist: prove the CLI works, confirm the active profile, inspect ~/.hermes/logs/agent.log, check allowed chats/topic IDs, and send one real message in the exact Telegram DM/group/topic before changing BotFather settings. Use the Hermes Dashboard / Web UI as a status checkpoint, not as final proof of delivery.