To set up Hermes Agent Telegram, create a bot with @BotFather, put its token and your numeric user ID into Hermes, and run the gateway. The fastest route is the Create with QR button in the Hermes dashboard or desktop app, which does all of that for you. After that, your agent lives in your pocket: you text it, send voice notes, and get cron results back in the same chat.
📺 Watch: Hermes Agent Just Launched Its Official Mobile App!
🔥 Get the Agent OS as a free bonus: AI Profit Boardroom members get the full Agent OS zip, prompt libraries, daily tutorials and weekly live coaching calls. → Get inside
This guide covers both setup routes, the privacy-mode trap that breaks most group setups, and the allowlist and pairing steps that keep strangers out. If you want a group of people building the same kind of agent workflows, the AI Profit Boardroom is where members share their Hermes setups each week.
Why Telegram is the easy first platform for Hermes
The Hermes gateway is one background process that connects to every messaging platform you configure, handles sessions, runs cron jobs and delivers voice messages. Telegram is the quickest one to connect. It needs no public URL, because Hermes uses long polling by default: the gateway reaches out to Telegram, so it runs fine on a laptop behind a home router.
Since v0.23.0, released on 5 November 2026, one gateway per machine owns every session. Nous Research says the CLI, TUI, desktop app, editors, bots and cron all attach to it as clients, with one queue and one history. So a chat you start in the terminal and continue in Telegram is the same chat. Earlier builds could run separate copies of the agent against one conversation, which is how messages got written twice or went missing.
If you are still choosing a platform, the best messaging app for Hermes Agent page compares them. This page is only about Telegram.
Hermes Agent Telegram setup: two routes
Route 1: Create with QR (fastest)
Open Messaging, then Telegram, in the Hermes dashboard or the desktop app. Click Create with QR and scan the code with your phone, or open the link. According to the Hermes docs, Hermes then creates the bot, detects your Telegram user ID, writes TELEGRAM_BOT_TOKEN and TELEGRAM_ALLOWED_USERS into your profile's .env file, and restarts the gateway. That is the whole job.
Route 2: Manual setup with BotFather
- Open Telegram, search for @BotFather and send /newbot.
- Pick a display name. Anything works, such as "Hermes Agent".
- Pick a username. It must be unique and end in "bot", such as my_hermes_bot.
- Copy the API token BotFather sends back. Anyone with this token controls your bot. If it leaks, send /revoke to BotFather straight away.
- Get your user ID by messaging @userinfobot (or @get_id_bot). It is a number like 123456789, not your @username.
- Run hermes gateway setup, pick Telegram, and paste the token and your user ID. Or add TELEGRAM_BOT_TOKEN and TELEGRAM_ALLOWED_USERS to ~/.hermes/.env yourself.
- Start it with hermes gateway. The bot should come online within seconds. Send it a message to check.
To keep it running after you close the terminal, use hermes gateway install for a user service (launchd on macOS), or sudo hermes gateway install --system for a Linux boot service. Optional BotFather polish: /setdescription, /setuserpic and /setcommands for the command menu.
📺 Watch: New Hermes Agent Mobile App Is Absolutely INSANE!
Lock it down: allowlist and pairing
Your Hermes bot can run terminal commands, so who can reach it matters. The Hermes docs state that by default the gateway denies every user who is not on an allowlist or paired via DM. You have two ways in.
Allowlist. Put the numeric IDs in TELEGRAM_ALLOWED_USERS, comma-separated, for example TELEGRAM_ALLOWED_USERS=123456789,987654321. GATEWAY_ALLOWED_USERS does the same across every platform.
DM pairing. When someone not on the list messages the bot, they get a one-time code such as XKGH5N7P. You approve them from your terminal:
- hermes pairing approve telegram XKGH5N7P lets them in.
- hermes pairing list shows pending and approved users.
- hermes pairing revoke telegram 123456789 removes access.
Codes expire after one hour and are rate-limited. There is also GATEWAY_ALLOW_ALL_USERS=true, which the docs mark as not recommended for bots with terminal access. Leave it off.
Inside the allowlist, you can split admins from regular users. Admins run every slash command. Regular users can chat but only run the commands you enable. The floor is /help and /whoami.
Want a second pair of eyes on how your agent should be locked down for a team? Book a free AI strategy session.
📺 Watch: 776 NEW Hermes Agent Updates Are INSANE! 🤯
Groups: the privacy mode trap
The Hermes docs call privacy mode the single most common source of confusion with Telegram bots. It is on by default. With it on, your bot in a group only sees messages that start with a / command, replies to its own messages, service messages, and messages in channels where it is an admin. Normal chatter never reaches Hermes.
To turn it off: message @BotFather, send /mybots, pick your bot, then Bot Settings, Group Privacy, Turn off. Then remove the bot from the group and add it back. Telegram caches the privacy state when a bot joins, so skipping this step means nothing changes. The other option is to make the bot a group admin, since admin bots get every message.
Once the bot can see the group, you control when it speaks:
| Setting | What it does | When to use it |
|---|---|---|
| require_mention: true | Answers only replies to the bot, @botusername, /command@botusername, or a mention_patterns wake word | Busy groups where the bot should stay quiet |
| observe_unmentioned_group_messages: true | Saves group chatter as context but only replies when triggered | You want "what did we decide earlier?" to work |
| exclusive_bot_mentions | Only the mentioned bot answers when several Hermes bots share a group (on by default) | Running more than one Hermes profile in one group |
| allowed_topics / ignored_threads | Whitelists or mutes specific forum topics | Forum groups with topics for different jobs |
| /sethome | Marks the chat as the home channel where cron results land | Daily reports or reminders to one chat |
Your allowlist still applies in groups. Only authorized users can trigger the bot, even when everyone can see it. If you run several Hermes bots, give each one its own token and gateway. Telegram rejects two gateways polling the same token.
Voice notes, files and topics
Voice in. Voice notes are transcribed and fed to the agent as text. You can use local faster-whisper with no API key, Groq Whisper with GROQ_API_KEY, or OpenAI Whisper with VOICE_TOOLS_OPENAI_KEY. For more on spoken replies, see Hermes Agent voice mode.
Voice out. Text-to-speech arrives as round Telegram voice bubbles. OpenAI and ElevenLabs output works as is. Edge TTS, the default free provider, needs ffmpeg (brew install ffmpeg on a Mac). Without it you get a plain audio file instead.
Big files. Telegram's public Bot API caps downloads at 20 MB. The docs show how to run a local telegram-bot-api server, which lifts the limit to 2 GB. That covers long meeting recordings.
Parallel chats. Send /topic in your DM with the bot to turn on multi-session mode. Each topic you create is its own Hermes session, so research and admin work never mix.
Cron is where Telegram pays off. Set a home channel, then schedule jobs that report to it. The Hermes Agent cron job guide covers the scheduling side.
Hermes Cloud and Team Gateway
On a Hermes Cloud instance with Team Gateway on, Telegram runs through a shared Hermes bot instead of your own. The Telegram card says Via Team Gateway. Click Link Telegram, and Hermes shows a one-time message such as /link AB12CD with a QR code. Send that message to the shared bot from your Telegram account, and the card lists you as linked. To run your own bot beside it, set GATEWAY_RELAY_ALLOW_DIRECT_PLATFORMS=true. The docs note that keeps a live connection open, so the instance never sleeps. More on that setup in our Hermes Cloud page.
For cloud hosts that sleep when idle, the docs recommend webhook mode. Set TELEGRAM_WEBHOOK_URL and Telegram pushes updates to you instead of Hermes polling.
Where Telegram fits with the other gateways
Telegram is often the personal channel, with Slack or Discord for the team. One gateway can hold all of them. Our Hermes multi-gateway connections guide shows how they share one process. Sibling guides: Hermes Agent Slack, Hermes Agent Discord and Hermes Agent WhatsApp. If you want a Telegram bot that is not Hermes, the older Telegram AI agent page covers other routes.
To see how the full system fits together, read the Agent OS guide. To pick a model for the bot, check Goldie Bench.
Inside the AI Profit Boardroom, members post the Telegram bots they run for their businesses, with the prompts and cron jobs behind them. If you want help mapping which jobs to hand to an agent first, grab a free AI strategy session.
FAQ
Why does my Hermes bot work in DMs but ignore my group?
Privacy mode is on. Turn it off in BotFather under Group Privacy, then remove and re-add the bot. Or make the bot a group admin. Also check that the person messaging is on TELEGRAM_ALLOWED_USERS.
Does the Telegram bot see every message in a group by default?
No. With privacy mode on, it only sees commands, replies to itself, service messages and channels where it is admin.
How do I let a teammate use my bot?
Add their numeric ID to TELEGRAM_ALLOWED_USERS, or have them DM the bot and approve the code with hermes pairing approve telegram plus the code. Codes last one hour.
What is the largest file I can send?
20 MB through Telegram's public Bot API. With a local telegram-bot-api server, it rises to 2 GB.
Ready to put a Hermes bot to work on real business tasks? Book a free AI strategy session and plan the first three jobs it should take off your plate.
