Hermes Agent Telegram: Set Up Your Bot In 6 Steps (2026)

Hermes Agent Telegram setup takes one bot token, one numeric user ID and one running gateway, and the order you do them in decides whether the bot answers on the first try.

This is the exact sequence I'd follow, from creating the bot to locking down groups, voice notes and big files.

Every setting below comes from the official Hermes Telegram docs, which match release v0.23.1 from 9 November 2026.

If you'd rather have my team look at where a Telegram agent fits your business before you build one, book a free SEO strategy session.

What You Are Actually Connecting

Telegram doesn't talk to the agent directly.

The Hermes messaging gateway sits in the middle: one background process that connects every platform you configure, keeps the sessions, runs scheduled jobs and sends voice replies.

Since v0.23.0 (5 November 2026), one gateway per machine owns every session.

The CLI, the desktop app, editors, bots and cron all attach to it as clients.

So the chat you start on your phone in Telegram is the same chat you see on your laptop, with one queue and one history.

That's the main reason to wire Telegram up at all: your agent goes where your phone goes.

Step 1: Pick Your Route, QR Or BotFather

There are two ways in, and I'd pick based on how you installed Hermes.

Route A, Create with QR. Open Messaging → Telegram in the Hermes dashboard or desktop app and press Create with QR.

Scan the code in Telegram and Hermes builds the bot, finds your user ID, writes TELEGRAM_BOT_TOKEN and TELEGRAM_ALLOWED_USERS into your profile's .env, and restarts the gateway.

The docs describe that button for the dashboard and desktop app, so on a CLI-only server go with Route B.

Route B, BotFather by hand. Message @BotFather, send /newbot, pick any display name, then pick a unique username that ends in bot.

BotFather replies with an API token shaped like 123456789:ABC....

Treat it like a password: whoever holds it controls the bot, and /revoke in BotFather kills a leaked one.

Step 2: Get Your Numeric User ID

Hermes gates access by number, not by @username.

Message @userinfobot and it replies with an ID like 123456789.

@get_id_bot is the backup the docs list.

Collect the same number from every person who should be able to use the bot.

Step 3: Write The Config And Start The Gateway

The wizard is the cleanest path.

hermes gateway setup        # choose Telegram, paste token + user IDs
hermes gateway              # run in the foreground to test

Prefer files? Put two lines in ~/.hermes/.env.

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789,987654321

Send the bot a message and it should answer within seconds.

Once it does, stop the foreground run and install it as a service so it survives logouts and reboots.

hermes gateway install                 # user service (launchd on macOS)
sudo hermes gateway install --system   # Linux boot-time service

🔥 Want a Telegram agent that's already wired into a full Agent OS? Inside the AI Profit Boardroom you get step-by-step video trainings, the installable Agent OS, four coaching calls a week and 3,400+ members sharing the gateway setups they actually run. → Join the AI Profit Boardroom

Step 4: Lock Access With Allowlists Or Pairing

Out of the box, the gateway refuses anyone who isn't on an allowlist or paired, which is exactly what you want for a bot that can reach a terminal.

For a fixed team, the allowlist is enough.

For people you add over time, use DM pairing instead.

The new person messages the bot and gets a one-time pairing code.
They send you that code by any channel.
You run hermes pairing approve telegram CODE on the machine.
They're in straight away, with no gateway restart.

The team Telegram assistant guide adds the guard rails: codes expire after one hour, each user can request one every 10 minutes, and five failed approvals lock the platform for an hour.

hermes pairing list shows who's pending and approved, and hermes pairing revoke telegram USER_ID removes someone.

Never flip GATEWAY_ALLOW_ALL_USERS=true on a bot with terminal access; the docs flag it as not recommended for exactly that reason.

Step 5: Fix Groups Before You Add The Bot To One

Privacy mode is the trap that catches most people, and the docs call it the single most common source of confusion.

It ships switched on.

With it on, the bot in a group only receives slash commands, replies to its own messages, service messages and posts in channels where it's an admin.

To change it: BotFather → /mybots → your bot → Bot Settings → Group Privacy → Turn off.

Then remove the bot from each group and add it back, because Telegram keeps the old setting for existing memberships.

The other option is to promote the bot to group admin, which gets it every message without touching the global switch.

Seeing messages isn't the same as answering them, so I'd add a mention rule straight away.

telegram:
  require_mention: true
  mention_patterns:
    - "^\s*hermes\b"

With require_mention on, the bot only acts on replies to it, @botname mentions, /command@botname and any wake-word pattern you set.

Leave it unset and Hermes replies to every group message it can see.

Step 6: Decide Who Can Do What In Groups

TELEGRAM_ALLOWED_USERS still applies inside groups, so a stranger in a group can't trigger the bot.

Two extra gates give you finer control.

Setting	What it allows	DM access?
`TELEGRAM_ALLOWED_USERS`	Listed people, everywhere	Yes
`TELEGRAM_GROUP_ALLOWED_USERS`	Listed senders, in groups only	No
`TELEGRAM_GROUP_ALLOWED_CHATS`	Every member of the listed groups	No

Group IDs are negative numbers like -1001234567890, and they go in the chats list, not the users list.

If staff should chat but not run commands, add allow_admin_from and user_allowed_commands to the Telegram extra block, and anyone can check their tier with /whoami.

Voice Notes In, Voice Bubbles Out

Send a voice memo and Hermes transcribes it before the agent reads it.

local runs faster-whisper on your own machine and needs no API key.
groq needs GROQ_API_KEY.
openai needs VOICE_TOOLS_OPENAI_KEY.

Spoken replies arrive as round Telegram voice bubbles.

Edge TTS, the default free provider, outputs MP3, so install ffmpeg or the replies land as plain audio files instead of bubbles.

Set stt.enabled: false if you want the agent to get the raw .ogg path and run its own transcription.

The 20 MB Wall And How To Lift It

Telegram's public Bot API caps file downloads at 20 MB, and Hermes answers anything bigger with a "too large" reply.

The documented fix is to run a local telegram-bot-api server in --local mode, which raises the ceiling to 2 GB.

Get an api_id and api_hash from my.telegram.org/apps.
Run the server bound to 127.0.0.1 only.
Log the bot out of the public API once with the logOut call.
Set base_url, base_file_url and local_mode: true under platforms.telegram.extra.
Run hermes gateway restart and check the log line.

Two gotchas: keys under a top-level telegram.extra are silently dropped, and port 8081 must never face the public internet because the server trusts anyone who knows the token.

Cloud Hosts, Proxies And Missed Messages

Hermes polls Telegram by default, which suits a laptop or an always-on box.

On a host that sleeps when idle, switch to webhook mode with TELEGRAM_WEBHOOK_URL plus a TELEGRAM_WEBHOOK_SECRET, and the gateway won't start without that secret.

If Telegram is blocked on your network, set telegram.proxy_url to an http, https or socks5 address.

Messages sent while the gateway was off wait in Telegram's queue for up to 24 hours and get answered in order on the next start.

On a server where a restart should mean a clean slate, set drop_pending_on_cold_boot: true.

Hermes Cloud: The Shared Bot Instead Of Yours

On a Hermes Cloud instance with Team Gateway on, you don't create a bot at all.

Telegram reaches your agent through a shared Hermes bot, and the card reads Via Team Gateway instead of Create with QR.

Click Link Telegram to get a one-time message like /link AB12CD plus a QR code.
Send that message to the shared bot from the Telegram account you'll use.
Once the card lists your account, message the shared bot to reach your agent.

The gateway has to be running for the link button to work.

Want your own bot alongside it? Set GATEWAY_RELAY_ALLOW_DIRECT_PLATFORMS=true, knowing the instance then never sleeps.

This linking flow shipped in v0.22.7 on 3 November.

📞 Rather have my team plan the setup with you? Book a free SEO strategy session and we'll look at where an always-on agent saves your team the most back-and-forth. → Book your free session

Three Small-Business Setups, Step By Step

A plumber running jobs from the van

Allowlist just the owner's user ID.
After each job, record a voice note: address, parts used, what's left.
Hermes transcribes it and the agent turns it into a tidy job note.
Run /sethome in the DM, then ask for a weekday 7am brief of open jobs, which lands in that chat.

A five-person agency sharing one bot

Create one group, turn privacy mode off, then re-add the bot.
Put the group ID in TELEGRAM_GROUP_ALLOWED_CHATS and set require_mention: true.
Staff tag @agencybot to draft a client update; everyone else's chatter is ignored.
Write "draft only, don't send" into each request, so a person always sends the final message.

An accountant reviewing documents

Send a client's PDF or spreadsheet under 20 MB straight to the DM.
Ask the agent for a summary and the questions to raise with the client.
The agent can return a file with a MEDIA: tag, delivered as a native attachment.
If the terminal runs in Docker, mount an output folder so the file path exists on the host.

Safety Settings I'd Switch On From Day One

Keep the allowlist tight and use pairing for newcomers.
Leave exec approval alone: risky commands prompt you, and a "yes" or "no" reply in the chat settles it.
Run the terminal in Docker on a shared team bot, as the team guide recommends.
Keep notifications on important, the default, so only final answers and approvals ring your phone.
Use /stop to end a run and /new to start fresh, because gateway chats don't reset on their own.

The full rules sit in the Hermes security docs, and for scheduled briefs to your new home channel, my Hermes cron job walkthrough picks up where this leaves off.

When It Works In DMs But Not In The Group

Check these in order, as the troubleshooting section lists them.

Is Telegram delivering the message? Privacy off, admin, or a direct mention.
Did you re-add the bot after changing privacy?
Is the sender or the group on an allowlist?
Is require_mention filtering it out?
With several Hermes bots, does each profile have its own token? Two gateways can't poll with one token.

Nine times out of ten it's step 1 or 2.

🔥 Get the full Agent OS build, Telegram included Inside the AI Profit Boardroom you get the video trainings, the installable Agent OS, four weekly coaching calls and a community of 3,400+ members to check your config against. → Join the AI Profit Boardroom

Also On Our Network

FAQ: Hermes Agent Telegram

Why does my Hermes bot ignore messages in a Telegram group?

Privacy mode is on by default, so the bot only sees commands, replies to it and a few service messages. Turn it off in BotFather and re-add the bot, or make it a group admin.

Do I need a username or a number for TELEGRAM_ALLOWED_USERS?

A number. Message @userinfobot to get your numeric Telegram user ID, and use commas to list several people.

Can the bot read files bigger than 20 MB?

Not on the public Bot API. Running a local telegram-bot-api server in --local mode and pointing Hermes at it raises the limit to 2 GB.

How do I add a teammate without restarting the gateway?

Use DM pairing. They message the bot, get a code, and you run hermes pairing approve telegram with that code. It takes effect at once.

Do I create my own bot on Hermes Cloud?

Not with Team Gateway on. You click Link Telegram and send the one-time /link code to the shared Hermes bot instead.

📺 Video notes + links to the tools 👉

🎥 Learn how I make these videos 👉

🆓 Get a FREE AI Course + Community + 1,000 AI Agents 👉

About Julian

I'm Julian Goldie, an SEO entrepreneur, author and founder of the AI Profit Boardroom, which has 3,400+ members.

I help business owners scale with AI agents, automation and SEO.

I've built a 7-figure SEO and link building agency, Goldie Agency, with a team of 70+ SEO experts.
I've grown a YouTube channel to 400,000+ subscribers.
I wrote "Link Building Mastery".
My Udemy courses have taught over 29,000 students.

→ Get my best AI training inside the AI Profit Boardroom

Work through the six steps in order, and if you want my team to map out what the bot should handle first, book a free strategy session before you finish your Hermes Agent Telegram setup.