# How to set up Hermes Agent on Telegram

> Connect Hermes Agent to Telegram: create a bot with Create with QR or BotFather, set your allowlist, start the gateway and chat from your phone.

Canonical: https://hermeswatcher.com/learn/hermes-agent-telegram-setup  
Section: Learn · Messaging & the gateway  
Last reviewed: Oct 29, 2026  
Basis: Explained from the official Hermes Agent docs and repository (Nous Research). Steps follow the linked official sources.

## 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](https://hermeswatcher.com/learn/messaging-gateway-explained.md). Compare platforms at [messaging platforms](https://hermeswatcher.com/messaging.md).

- 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](https://t.me/BotFather).
- 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](https://hermeswatcher.com/troubleshoot/task-finished-but-no-delivery.md).

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](https://hermeswatcher.com/learn/run-hermes-agent-24-7.md). For how the gateway handles sessions and platforms, see [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md).

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](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md).

- 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](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/telegram)

## Related guides

- [All messaging platforms](https://hermeswatcher.com/messaging.md)
- [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md)
- [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md)
- [Hermes Agent task finished but no message arrived](https://hermeswatcher.com/troubleshoot/task-finished-but-no-delivery.md)

## Related tools

- [Wake up to a useful research briefing](https://hermeswatcher.com/workflows/daily-research-briefing.md)
- [Know whether an automation actually worked](https://hermeswatcher.com/workflows/reliable-recurring-automation.md)
- [Telegram: reach Hermes from a private bot conversation](https://hermeswatcher.com/tools/telegram.md)
- [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md)
- [Command approvals: decide what the agent may run unattended](https://hermeswatcher.com/tools/approvals-security.md)
- [Scheduled tasks: automate a proven run](https://hermeswatcher.com/tools/scheduling.md)

## Sources

- [Telegram](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/telegram)
- [Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging)
- [Tutorial: Team Telegram Assistant](https://hermes-agent.nousresearch.com/docs/guides/team-telegram-assistant)
- [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security)
- [Gateway authorization and pairing policy (pinned source)](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/gateway/authz_mixin.py#L653-L773)
- [Scheduled delivery defaults](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron)
- [Voice mode and speech-provider requirements](https://hermes-agent.nousresearch.com/docs/user-guide/features/voice-mode)

---

HermesWatcher is an independent guide. It is not affiliated with or endorsed by Nous Research. The [official Hermes Agent documentation](https://hermes-agent.nousresearch.com/docs) and [repository](https://github.com/NousResearch/hermes-agent) from Nous Research are the authority; each page here lists the official sources it was written from. If this site and the official docs disagree, trust the official docs. Index for agents: https://hermeswatcher.com/llms.txt