How to set up Hermes Agent on Telegram

What you need

Hermes Agent can run as a Telegram bot. Once it is connected, you can chat with your agent from any device, send voice memos for transcription through your configured speech provider, and receive scheduled-task results. It supports text, voice, images and file attachments.

Setup has three parts: create a bot, tell Hermes who may use it, and start the messaging gateway. An allowlist is the list of people permitted to use your agent. For background, see Hermes Agent messaging gateway explained. Compare platforms at messaging platforms.

• Hermes Agent installed, with a model provider configured.
• A Telegram account.
• Your numeric Telegram user ID. This is not your @username. The steps below show how to find it.
• A machine that stays on, if the bot should always answer. A laptop works while it is awake. For a bot that stays available, the official team tutorial uses a server or VPS.

Create the bot

The quickest route is the Create with QR button on the Messaging → Telegram page in the Hermes dashboard and the desktop app. Scan the code, or open the link, in Telegram. Hermes creates the bot for you, detects your Telegram user ID, writes TELEGRAM_BOT_TOKEN and TELEGRAM_ALLOWED_USERS into your profile's .env, and restarts the gateway. If you use it, skip ahead to sending your first message.

To create the bot yourself, use @BotFather, Telegram's official bot management tool.

• Open Telegram and search for @BotFather, or open BotFather in Telegram↗ (opens in a new tab).
• Send /newbot.
• Choose a display name, for example "Hermes Agent".
• Choose a username. It must be unique and end in bot, for example my_hermes_bot.
• BotFather replies with your API token. It looks like 123456789:ABCdefGHIjklMNOpqrSTUvwxYZ.

Keep the token secret. Anyone with it can control your bot. If it leaks, revoke it straight away with /revoke in BotFather.

Connect it to Hermes

Hermes uses numeric Telegram user IDs to control access. Message @userinfobot and it replies with your ID, a number like 123456789.

Then run the setup wizard and select Telegram. It asks for your bot token and allowed user IDs, then writes the configuration for you. If you prefer to edit the file yourself, add the two lines shown below to ~/.hermes/.env. Separate multiple user IDs with commas.

Terminal

hermes gateway setup

~/.hermes/.env (manual option)

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789

The gateway does not execute unknown users' requests without an explicit grant. An allowlisted user, an approved DM pairing or another supported grant can authorize access. An absent allowlist does not revoke an approved pairing. Keep allow-all disabled on a private bot, including GATEWAY_ALLOW_ALL_USERS.

DM pairing is an alternative to a fixed list. Without a restrictive policy, an unknown DM can receive a one-time code. With an explicit allowlist, current gateway code normally suppresses unsolicited codes unless the platform policy opts into pairing. Approve an issued code on the host with hermes pairing approve telegram <code>. Codes expire after one hour. hermes pairing list shows pairing state. hermes pairing revoke telegram <user-id> removes a pairing grant; also remove any allowlist entry that still grants access.

Authorized people can reach this profile's configured tools, including terminal access by default. The allowlist controls who can ask, while tool, approval and sandbox settings control what the agent may do. Review those settings before allowing anyone else.

Start the gateway and send your first message

Run the gateway in the foreground first so you can watch it start.

Terminal

hermes gateway

With the gateway running, find your bot in Telegram and send a harmless message from your allowed account. Check that its reply reaches that conversation and inspect the gateway output for errors. Press Ctrl+C to stop the foreground gateway.

/new starts a fresh conversation. /sethome chooses this chat as the home destination for a bare telegram delivery target. Chat-created scheduled jobs default to their origin; CLI-created jobs default to local output. Explicit chat or topic targets select their own destination. See Hermes Agent task finished but no message arrived.

When the agent wants to run a potentially dangerous command, it asks for approval in the chat. Reply "yes" or "y" to approve, or "no" or "n" to deny.

What it can do

The official comparison table lists voice, images, files, threads, typing and streaming. It leaves reactions unmarked, while the Telegram page describes them. They are off by default; enable them with telegram.reactions: true in config.yaml or TELEGRAM_REACTIONS=true. Voice means notes or spoken replies, not a live call.

Voice features depend on your configured speech provider. Local faster-whisper is the normal local transcription engine where supported; native Windows ARM64 and Intel macOS do not receive it. Use a supported hosted or command-based provider there. Voice notes and spoken replies are separate from live voice conversations.

Keep it running

The bot is silent while its computer sleeps or is switched off. Keep the Hermes host awake and online whenever you need replies. A background service does not prevent sleep. Closing the lid usually puts a laptop to sleep, and the bot goes quiet.

A foreground gateway stops when you close the terminal. Install it as a background service instead: a user systemd service on Linux, a launchd service on macOS, or a Scheduled Task that runs at logon on Windows.

Install the service

hermes gateway install

Start it

hermes gateway start

Check it

hermes gateway status

On a Linux server you never log into, the docs suggest running sudo loginctl enable-linger $USER once, so the user service starts at boot and survives logout.

For hosting choices, see How to run Hermes Agent 24/7 on a VPS or home server. For how the gateway handles sessions and platforms, see Hermes Agent messaging gateway explained.

When this computer is off, asleep or disconnected, Hermes cannot process messages or run scheduled jobs. A background service does not keep a powered-off host running. On Windows, Task Scheduler watches the launcher rather than later gateway crashes. Check hermes gateway status and use hermes gateway start if it has stopped.

Messages sent while the computer was off

Telegram drops pending updates on a cold boot by default. Set platforms.telegram.extra.drop_pending_on_cold_boot: false in config.yaml to receive that backlog. Old commands can run later, and a crash can repeat an update that was partly processed. Only turn this on if you are happy for old messages to run as tasks later.

Optional config.yaml: receive pending updates after a cold boot

platforms:
  telegram:
    extra:
      drop_pending_on_cold_boot: false

Group chats and permissions

Telegram bots have privacy mode turned on by default. With it on, the bot only sees messages that start with a / command, replies to its own messages, service messages, and messages in channels where it is an admin.

Visibility, authorization and mention rules are separate gates. A message must reach the bot, its sender or group must have an execution grant, and the message must pass any mention filter. Changing privacy mode alone does not grant agent access.

• To let the bot see every group message, message @BotFather, send /mybots, select your bot, then go to Bot Settings → Group Privacy → Turn off.
• After changing privacy, remove the bot from the group and add it again. Telegram keeps the old setting until you do.
• Instead of turning privacy off, you can promote the bot to group admin. Admin bots receive all messages.
• TELEGRAM_ALLOWED_USERS grants sender access in DMs and groups. It is one option alongside approved pairing and the group grants below.
• TELEGRAM_GROUP_ALLOWED_USERS lets listed people use the bot in groups without giving them DM access. A chat ID in TELEGRAM_GROUP_ALLOWED_CHATS authorizes every member of that group. Group chat IDs are negative numbers.
• Set telegram.require_mention: true so the bot only answers replies to it, @mentions and commands addressed to it. If it is unset, the bot responds to normal group messages it can see.

If it doesn't answer

Most setup issues come down to the token, the allowlist or privacy mode. For a wider checklist, see Hermes Agent bot not responding in your chat app.

• Bot not responding at all: check that TELEGRAM_BOT_TOKEN is correct and read the hermes gateway logs for errors.
• Bot ignores you, or replies "unauthorized": your user ID is probably not in TELEGRAM_ALLOWED_USERS. With an allowlist set, Hermes normally stays silent to unknown users. Check the number with @userinfobot.
• Bot ignores group messages: privacy mode is probably on. Turn it off or make the bot an admin, then remove and re-add it.
• Token revoked or invalid: get a new one in BotFather with /revoke, then /newbot or /token, and update your .env file.

Official docs

Reviewed Oct 29, 2026 against the official Hermes docs.

Official Hermes Telegram docs↗ (opens in a new tab)

Related guides

• All messaging platforms
• Hermes Agent messaging gateway explained
• Hermes Agent bot not responding in your chat app
• Hermes Agent task finished but no message arrived

Spotted something wrong or out of date? Tell us on X at @HermesWatcher↗ (opens in a new tab) and we will fix it.

New Hermes Agent updates every day on X. Follow @HermesWatcher