ع
🤖 AI Agents

Connect Hermes Agent to Telegram: Your AI Agent in Your Pocket

One bot token, one user ID, five minutes — and the full agent answers from your phone: files, tools, schedules and all. The complete setup, plus the security settings most guides skip.

Beginner10 min read

What you'll be able to do by the end

  • Create your own Telegram bot with BotFather and keep its token safe
  • Connect Hermes to Telegram with the interactive gateway wizard
  • Send commands from your phone and get real agent work back
  • Lock the bot down so only you can talk to it
  • Fix the four connection problems beginners actually hit

Before you start

  • Hermes installed and chatting locally (see our Desktop setup guide)
  • Telegram installed on your phone or desktop

Here’s the moment the agent stops being software-you-open and becomes something that lives with you: you text it from your phone — “pull the sales numbers from yesterday’s report and draft the summary email” — and by the time you’ve poured your coffee, the draft is waiting in the same chat.

That’s Hermes on Telegram. Same agent, same tools, same memory as your terminal — reachable from anywhere. Setup takes minutes, and this guide includes the security steps that make it safe to leave running.

Why Telegram specifically

Because it turns the agent from a place you go into a thing that talks to you. Three practical wins:

  • Reachable everywhere — full tool access from your phone, tablet, or any computer with Telegram.
  • Voice-native — send a voice memo; it arrives transcribed. Ask for spoken replies and they come back as playable voice bubbles.
  • A natural notification channel — scheduled jobs deliver their results into the chat, so your morning briefing lands where you already look.

Discord, Slack, WhatsApp and others work through the same gateway; the steps differ slightly but the model is identical. Telegram is simply the fastest to set up.

Creating the bot: two minutes in BotFather

Every Telegram bot starts the same way — through @BotFather, Telegram’s official bot manager:

  1. Open Telegram and message @BotFather.
  2. Send /newbot.
  3. Pick a display name — anything (“Omar’s Hermes”).
  4. Pick a username — globally unique, must end in bot.
  5. Copy the API token from the reply. It looks like 123456789:ABCdefGHI....

That token is now the most sensitive string in this setup: whoever holds it is your bot. It goes into Hermes’ secret store and nowhere else — not screenshots, not repos, not chats. If it ever leaks, /revoke in BotFather kills it instantly and a new one takes its place.

While you’re there, optional polish: /setdescription and /setabouttext give your bot a friendly profile, and /setcommands builds the menu that appears when someone taps the / button.

Connecting Hermes: the wizard path

On the machine where Hermes lives:

hermes gateway setup

Choose Telegram. Paste the token when asked. When asked who’s allowed in, give it your numeric user ID — the number from @userinfobot, not your @username. The wizard writes everything correctly and you’re done configuring.

Manual alternative, if you’d rather: add these lines to ~/.hermes/.env —

TELEGRAM_BOT_TOKEN=123456789:ABCdef...
TELEGRAM_ALLOWED_USERS=123456789

Then start the gateway:

hermes gateway

Within seconds the bot appears online in your contact list. Say hello. Give it a real task — “list the PDFs in my documents folder” — and watch it work from across the room.

What you can do from the chat

Everything, is the short answer. The long version worth knowing:

  • Real agent work: files on your computer, web searches, document analysis, code fixes — the same toolset as the CLI.
  • Slash commands: /help, /new (fresh conversation), /model, /topic for separate parallel conversations.
  • Approvals in-chat: dangerous commands produce a yes/no prompt right there — nothing destructive happens from your pocket unapproved.
  • File delivery: generated documents, spreadsheets, images and archives arrive as native Telegram attachments.
  • Scheduled deliveries: connect this with cron (next article in the series) and your daily briefings arrive here automatically.

Security and privacy, seriously

A messaging-connected agent deserves more respect than a terminal session, because anyone who can reach it inherits its powers. The essentials:

Allowlist by ID. TELEGRAM_ALLOWED_USERS is the gate. Without it the gateway denies all users by default — good — but set it explicitly to your ID and treat any addition as a deliberate decision.

Guard the token. It stays in .env on the machine running Hermes. Never in git, never in a screenshot. Compromised? /revoke and re-issue in minutes.

Assume the bot = the machine. Whatever files and credentials the host machine holds are within the agent’s reach, so run it somewhere appropriate. Approval prompts for dangerous operations are your second layer — don’t train yourself to auto-reply “yes”.

Groups raise exposure. Group use requires disabling privacy mode or granting admin, which lets the bot see ordinary messages. Do it consciously, prefer the observe-but-don’t-react configuration, and keep the allowlist tight regardless.

Troubleshooting: the four real problems

Symptom Cause & fix
Bot silent, nothing responds Gateway not running or token wrong — check hermes gateway output
“Unauthorized” reply Your ID missing/mistyped in TELEGRAM_ALLOWED_USERS — recheck via @userinfobot
Ignores group messages Privacy mode — turn off in BotFather or promote to admin, then remove & re-add the bot
Voice notes not transcribed Configure speech-to-text (local faster-whisper or a provider key)

One more pattern worth internalizing: after any privacy-mode change, remove the bot from the group and add it again. Telegram caches the old state — this trips up nearly everyone once.

Next steps

Your agent now follows you around. The last article in the series makes it proactive: Skills, Models & Automation covers reusable skills, picking models deliberately, and scheduling tasks that deliver results straight into this chat.

Missed the foundations? How to Set Up Hermes Desktop gets the local side ready, and What Is Hermes Agent? explains why any of this is possible.

Steps

  1. Step 1: Create the bot in BotFather

    In Telegram, open a chat with @BotFather (t.me/BotFather — Telegram's official bot manager) and send /newbot. Choose a display name (anything), then a username that must be unique and end in 'bot' (like omar_hermes_bot). BotFather replies with an API token that looks like 123456789:ABCdef... — this is the bot's identity and password in one string.

    Note: Treat the token like a password. Anyone holding it controls your bot. If it ever leaks, revoke it immediately with /revoke in BotFather.

  2. Step 2: Find your Telegram user ID

    Hermes allows access by numeric user ID — not your @username. Message @userinfobot (or @get_id_bot) and it instantly replies with your number, something like 123456789. Save it; the next step asks for it.

    Note: This number is how the gateway knows which humans are allowed in. Every future user you add will need theirs.

  3. Step 3: Run the gateway wizard

    On the machine running Hermes, run `hermes gateway setup`, choose Telegram, and paste the bot token and your user ID when asked. The wizard writes the configuration for you — no manual file editing needed. Prefer doing it by hand? Add TELEGRAM_BOT_TOKEN and TELEGRAM_ALLOWED_USERS to ~/.hermes/.env instead.

    Note: Keys belong in .env, settings in config.yaml — if you configure manually, keep that split.

  4. Step 4: Start the gateway and say hello

    Run `hermes gateway`. The bot comes online within seconds. Send it a message from your phone — 'What's in my home directory?' — and watch it answer by actually checking, not guessing. Voice notes work too: they arrive transcribed automatically.

    Note: The gateway must keep running for the bot to stay online. On your own machine, that means an open terminal or a background service.

  5. Step 5: Use it like the full agent

    From Telegram you get everything the CLI has: ask it to summarize documents on your computer, run scheduled reports, search the web, edit files. Slash commands work in chat too (/help, /new, /model). When the agent needs to run something potentially dangerous, it posts an approval prompt right in the chat — reply yes or no.

    Note: It can send files back: ask for a PDF or spreadsheet and it arrives as a native Telegram attachment.

  6. Step 6: Lock it down

    Three habits keep a Telegram agent safe: (1) TELEGRAM_ALLOWED_USERS set to only your ID — without it, the gateway denies everyone by default anyway, but verify it's really there; (2) the bot token never leaves .env — never commit it anywhere; (3) remember that whoever can message the bot can act on the machine it runs on, so don't run it on a box with secrets you can't afford to touch.

    Note: Planning group chats? Bots have privacy mode ON by default — they see only commands and replies unless you change it in BotFather, and groups require removing and re-adding the bot after that change.

Common mistakes — and how to avoid them

MistakeBot created, token pasted, nothing responds.

Do this insteadCheck that `hermes gateway` is actually running and look at its log output for errors — a wrong token shows up there immediately.

MistakeBot replies 'unauthorized' to you specifically.

Do this insteadYour numeric ID isn't in TELEGRAM_ALLOWED_USERS. Re-check it with @userinfobot — usernames don't count.

MistakeWorks in private chat, ignores the group.

Do this insteadThat's privacy mode. Disable it in BotFather (Bot Settings → Group Privacy) or make the bot a group admin — then remove and re-add the bot to the group so Telegram applies the change.

MistakeVoice messages come back as silent file attachments.

Do this insteadInstall ffmpeg — it converts text-to-speech audio into proper Telegram voice bubbles.

MistakeSharing the bot with friends by adding their usernames.

Do this insteadAccess works by numeric user ID only. Get each person's ID from @userinfobot and add those numbers, comma-separated.

❓ Frequently asked questions

Does the bot have access to my whole computer?

It has whatever the local Hermes installation has — same tools, same permissions as your terminal sessions. That's exactly why the allowed-users list and approval prompts matter: they define who can reach those tools remotely.

Is the bot free?

Telegram bots cost nothing. You pay only for the model usage behind the agent, same as running Hermes locally.

Can other people use my bot?

Only IDs in TELEGRAM_ALLOWED_USERS can interact; everyone else is denied by default. For shared use, add each person's ID deliberately — or better, read the security docs about pairing before opening it up.

What happens when my laptop is off?

The bot is offline too — the gateway runs where Hermes runs. Scheduled tasks wait until it's back. An always-on agent needs an always-on machine (an old box, a home server, or rented cloud).

Do voice messages really work?

Yes — incoming voice notes are transcribed automatically, and the agent can answer by voice. Speech-to-text uses a local model or a configured provider key; outgoing voice replies need ffmpeg installed.