Hermes Agent Telegram Setup: Connect a Telegram Bot

This page is the focused setup guide for connecting Hermes Agent to Telegram. It is different from the Telegram integration overview: the overview helps you decide whether Telegram is the right surface, while this article walks through the actual bot, token, config, verification, group, and troubleshooting path.

Telegram setup intent vs the other pages#

Searchers land here for phrases like “Hermes Agent Telegram setup” or “connect Hermes Agent to Telegram.” Keep the intent clean:

• Use this setup article when you need the step-by-step path from BotFather to a working Telegram bot.
• Use the Telegram integration page when you are comparing mobile/private-message workflows before setup.
• Use connect Telegram to Hermes when you want the shortest checklist version.
• Use Hermes Agent troubleshooting when the base CLI, provider, or gateway process fails before Telegram receives a message.
• Use Hermes Agent VPS hosting when the bot works locally but needs to stay online while your laptop sleeps.

That separation prevents duplicate thin content: overview pages explain fit, how-to pages give the short checklist, and this setup guide covers the operational details and failure modes.

Before you touch BotFather#

Start by proving the base agent works. A silent Telegram bot is often a Hermes config problem, not a Telegram problem.

1. Run one local Hermes prompt with the same profile you plan to expose through Telegram.
2. Confirm the model provider key works and the selected model can answer.
3. Confirm the profile can load memory and the tools you want Telegram to trigger.
4. Decide whether Telegram should run on your laptop, a VPS, Docker, or a managed service.
5. Decide the trigger policy: private messages only, group mentions only, or selected group topics.

If this sounds like too much infrastructure for a personal assistant, the commercial route is simpler: FlyHermes removes the server and gateway maintenance work while keeping Telegram-style delivery useful.

Step-by-step Telegram setup#

1. Create the bot in BotFather. In Telegram, message @BotFather, run /newbot, choose a display name, and copy the token. Treat the token like an API key.
2. Find your Telegram user ID. Message @userinfobot or another trusted ID helper, then copy your numeric user ID. Do not rely only on usernames for allowlisting.
3. Add the token to the correct Hermes profile. Put the token in the config or environment for the profile that will run the gateway. Never paste it into prompts, screenshots, or committed docs.
4. Restrict access before launch. Add your Telegram user ID to the allowed-user list so strangers cannot operate your agent through the bot.
5. Start or restart Hermes with the Telegram gateway enabled. Restart after config changes; stale gateway processes are a common reason a valid token appears broken.
6. Send one test message. Ask for a harmless visible action, such as “what profile are you running under?” or a tiny tool-backed lookup, so you can distinguish model replies from gateway routing.
7. Only then add groups or voice. Once private messages work, move to group mention behavior, voice notes, file uploads, cron delivery, or persistent server hosting.

The multi-platform gateway matters because Telegram should route into the same Hermes brain as your CLI, cron jobs, browser work, and Discord bot—not a separate chatbot that forgets your environment.

Telegram config decisions that affect safety#

A Telegram bot is a remote control for your agent. Configure it like one:

• Allowed users: start with your own user ID only, then expand intentionally.
• Group behavior: in groups, require direct mentions unless the room is dedicated to the bot.
• Profile isolation: use a separate Hermes profile for a public or team bot so personal memory and secrets do not leak.
• Tool scope: give the Telegram profile only the tools needed for that channel.
• Delivery target: if Telegram is only a notification channel for AI agent cron jobs, consider script-only jobs or read-only toolsets.
• Hosting: for always-on Telegram, compare self-hosting with VPS hosting before assuming your laptop is enough.

Troubleshooting Telegram gateway failures#

Work from the outside in:

• Bot does not respond at all: confirm the gateway process is running, the token is in the active profile, and the bot was restarted after the config edit.
• Bot responds to someone else: tighten the allowed-user list immediately and rotate the token if you exposed it.
• Private messages work but groups do not: add the bot to the group, check group privacy settings, and require mention-only behavior for safety.
• Telegram receives text but tools fail: debug Hermes tool permissions, not Telegram. The message reached Hermes; execution failed inside the profile.
• It worked yesterday but not today: inspect logs for a gateway crash, VPS reboot, expired process manager, or Docker container restart.
• Voice notes fail: set up voice mode separately; start with text messages, then follow the voice mode setup path.

If every Telegram-specific check passes, fall back to Hermes Agent troubleshooting and test the same prompt in the CLI. The CLI result tells you whether Telegram is the broken layer.

When to use FlyHermes instead#

Self-hosted Telegram is powerful when you want full control over the runtime, filesystem, credentials, and gateway process. It is also operational work. Choose FlyHermes if the real goal is “message my agent from Telegram” rather than “maintain a production bot stack.” Choose self-hosting if you need custom tools, private infrastructure, local files, or unusual gateway behavior.

Telegram memory issues are often profile or gateway issues#

If Hermes remembers things in the CLI but not in Telegram, inspect the gateway profile, session source, and provider logs before blaming memory itself. Recent support demand around memory, context, and gateway behavior makes this a common failure mode. Use the memory/context troubleshooting guide and consider FlyHermes if you want the hosted Telegram agent outcome without maintaining gateway restarts and VPS plumbing.

If Telegram breaks after an update#

Recent Discord evidence included no menu in choosing models in telegram. update failed and restart-loop reports. Telegram setup is not verified by a CLI-only smoke test: after running the Hermes update command hangs checklist, send an actual Telegram test message, inspect agent.log, and restart the gateway if platform code changed.