Hermes Agent Telegram Setup: BotFather, User IDs, Groups, and Topics

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.

Fix “blocked unauthorized user” first#

The most common authorization mistake is copying the numeric prefix from the BotFather token into the user allowlist. A token such as 123456789:ABC... starts with the bot account ID. Hermes needs the numeric ID of the human Telegram account sending the message. Those are different identities.

Use @userinfobot or @get_id_bot in Telegram to read your human user ID, then choose one authorization path:

# Guided path: the wizard asks for the bot token and allowed human user IDs
hermes gateway setup

# Manual env path: comma-separate human user IDs
TELEGRAM_ALLOWED_USERS=123456789,987654321

Hermes fails closed: when no user allowlist, approved pairing, or explicit allow-all policy exists, unauthorized users are denied. That is a safety feature because the Telegram toolset can include terminal, browser, file, and other powerful tools. Do not solve a private-bot setup by enabling global access.

If DM pairing is enabled, an unknown user can receive an eight-character code. Approve it from the machine running the same Hermes profile:

hermes pairing list
hermes pairing approve telegram ABC12DEF
hermes pairing revoke telegram 123456789

Docker users must run the approval as the unprivileged hermes user so the gateway can read the 0600 pairing file:

docker exec -u hermes hermes-agent hermes pairing approve telegram ABC12DEF

After changing an allowlist or pairing state, restart the correct profile's gateway and send a new DM. The gateway troubleshooting guide covers process-level proof when the config is correct but the running service is stale.

Telegram identity map: do not mix these numbers#

• Bot token: secret credential from BotFather. Its numeric prefix identifies the bot, not you.
• Human user ID: positive numeric account ID used by TELEGRAM_ALLOWED_USERS and pairing approvals.
• Private DM chat ID: normally the same number as the human user ID.
• Group or supergroup chat ID: negative number, commonly beginning with -100. Put chat-scoped access in the Telegram group/chat allowlist, not the human-user allowlist.
• Forum topic ID: message_thread_id inside a group or private-topic chat. It is not encoded in a normal private t.me/c/... message URL.

This distinction explains why a bot can connect successfully while every inbound message is logged as unauthorized. The token proves which bot Hermes controls; the allowlist proves which human may control Hermes through that bot.

Current setup and proof commands#

Use the shortest supported setup path, then prove each layer separately:

hermes gateway setup
hermes gateway restart
hermes gateway status
hermes chat -q "Reply with exactly: provider ok"

The CLI smoke test proves the provider can answer. The gateway status proves the service started. Only a reply in the real Telegram DM, group, or topic proves the integration. If you use a named profile, run the gateway and checks with hermes -p <profile> ... so a working default profile does not hide a broken bot profile.

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

Choose the right Telegram operating model#

Fresh June 2026 research shows why Telegram pages need more than “paste your bot token.” A recent Hermes Telegram tutorial walks through installing Hermes from scratch, choosing a provider/model, creating a BotFather bot, and then connecting Telegram. A Reddit Hermes profiles thread asks whether one Telegram bot can serve multiple agents and points to Docker, VMs, or separate machines when strict isolation matters. That means the real choice is operational:

• Private personal bot: one Hermes install, one profile, one Telegram DM, one smoke test.
• Group or forum-topic bot: start in DM, then verify allowed chats, mention/free-response rules, BotFather privacy, and message_thread_id in the exact topic.
• Multiple projects or agents: create separate Hermes profiles and usually separate bot tokens so secrets, skills, memory, sessions, and filesystem access do not bleed together.
• Always-on team/mobile access: self-host with VPS, Docker, launchd, or systemd only if you want to own uptime and logs; use FlyHermes when you want managed channel uptime instead.

Use the Hermes dashboard/Web UI as a checkpoint for gateway, provider, cron, memory, and profile state, but do not call Telegram healthy until a reply lands in the actual DM, group, or topic you care about.

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.

Telegram launch checklist#

Before you hand this to a team or rely on it for daily work, verify each layer in order:

1. hermes chat -q "reply ok" works in the same profile.
2. The BotFather token lives only in that profile's secret env file.
3. One private DM replies with the expected model/provider.
4. The dashboard/Web UI shows the expected gateway and provider state.
5. If using groups, the bot has the right privacy and mention/free-response behavior.
6. If using topics, the exact message_thread_id has been tested with a real message.
7. Provider costs and rate limits are understood before enabling voice notes, cron reports, or noisy group contexts.
8. If uptime is the business requirement, compare self-hosted vs hosted AI agent instead of turning a laptop into production infrastructure.

Network failures: when Telegram alone goes silent#

If several Telegram bots fail while Discord, cron, and the local CLI remain healthy, test the gateway host's route to api.telegram.org. Hermes supports telegram.proxy_url or TELEGRAM_PROXY with HTTP, HTTPS, and SOCKS5 proxies. Restart the correct profile after setting it, then retest the exact DM or topic. The gateway troubleshooting runbook separates this network case from wrong user IDs, topic routing, and provider failures.