How to Connect Hermes Agent to Telegram and Manage Tasks from Your Phone

You can message Hermes Agent or dictate tasks to it in Telegram from your phone when you’re away from your computer, and receive the result in the same chat. Scheduled task results arrive in the chat you designate as your home chat once.

If you don’t have Hermes yet, start with the guide on what this agent is and how to install it, then come back to connect Telegram.

Additional instructions are available in the Ailoot documentation.

What do you need to connect Hermes Agent to Telegram?#

The hermes doctor command checks your Hermes installation and model connection. We’ll create the bot in the Telegram app, and you’ll need a computer to run commands in the terminal.

How do you create a bot through BotFather?#

Every Telegram bot has a token — a secret key for controlling the bot. It is issued by Telegram’s official bot, @BotFather.

1. Open @BotFather

   Search for @BotFather in Telegram or open t.me/BotFather. The real BotFather has a blue verification checkmark. Start the conversation by tapping “Start.”

2. Send the /newbot command

   BotFather will ask for two names. The first is the display name; it can be anything, for example, “My Agent.” The second is the username: it must be unique and end in bot, for example, moy_agent_bot.

3. Get the token

   BotFather will send a congratulatory message and a long string in the form 123456789:ABCdefGHIjklMNOpqrSTUvwxYZ. This is the bot token. Copy the entire string.

There’s also a quick way that doesn’t require a manual conversation with BotFather. In the Hermes web dashboard (hermes dashboard) and in the desktop app, on the “Messaging → Telegram” page, there’s a “Create with QR” button: scan the code with your phone, and Hermes creates a bot, detects your ID, saves the token in the settings, and restarts the gateway. The steps below cover the manual method; if you chose QR, go straight to checking the connection.

How do you find your Telegram ID, and why do you need it?#

A Telegram account has two identifiers: a public username with an @ sign and an internal numeric ID. Hermes uses the number.

The quick “Create with QR” method described above detects your ID automatically. Write it down next to your token.

How do you give the token to Hermes Agent and start the gateway?#

1. Run the setup wizard

   hermes gateway setup
   

   Run the command on the machine where Hermes is installed. The wizard will offer a list of messaging apps.

2. Select Telegram and enter your details

   The wizard will ask for the bot token and the allowed IDs (you can enter several, separated by commas) and save everything in the settings itself.

3. Start the gateway

   hermes gateway
   

   The gateway will start and connect to Telegram. After a few seconds, send your bot any message from the app: if Hermes replies, the connection is ready.

The manual method instead of using the wizard looks like this: open the ~/.hermes/.env file and add two lines, substituting the token from BotFather and your numeric ID:

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789

The second line authorizes those people in private chats and groups; separate group-chat authorization can also grant access. Separate multiple people with commas. After saving the file, start the gateway with the same hermes gateway command.

If the bot stays silent even in a private chat, check the gateway logs in the same terminal and first verify the token and your ID in the access list; other errors are covered in the table at the end of the article.

What can the Telegram bot do on your phone?#

There are five capabilities you’ll most often need on your phone.

Text and voice messages. Write a task in words or dictate a voice message — with speech recognition configured, Hermes will transcribe it and understand it. With a local provider, no keys are needed; everything is processed on the machine where the agent runs.

Files and pictures. You can forward a document, spreadsheet, or screenshot to the bot — the agent will receive it as an attachment. It can also send generated files back: ask for a report, and it will send it as a file in the chat.

Confirmations for dangerous actions. When the agent is about to do something risky, such as delete files, it first asks in the chat: reply “yes” or “y” and it does it; reply “no” or “n” and it cancels.

Buttons instead of typing back. When the agent needs clarification, it sends a question with inline option buttons — tap an option, and the agent continues working. The /model command without arguments shows a model selection menu with the same kind of buttons.

Quiet notifications. By default, your phone rings only for final responses, confirmation requests, and command confirmations. Service notifications such as “calling a tool” and “compressing context” arrive silently, so your phone doesn’t ring at every step. If you want sound notifications at every step, switch the mode in the settings.

How do you get background task results in the chat?#

Home chat for scheduled tasks. Hermes supports scheduled tasks: “every morning at 7:43, put together a summary for me.” It sends the results to the home chat, which you designate once by sending the /sethome command directly in the conversation with the bot. As long as the gateway is running, summaries arrive automatically.

Background tasks. You can send a long task to run in the background and get on with your day: the bot will message you when it’s ready. A task started from a topic will return its answer to that same topic, so nothing gets lost.

Important limitation: the bot only replies while the gateway is running. If you turn off the computer running Hermes or put it to sleep, the bot won’t reply until the machine is running again. To keep the bot online all the time, move the agent to a server: we have a separate guide on how to keep Hermes Agent running around the clock. By default, the gateway polls Telegram for new messages; for cloud platforms that go to sleep without incoming traffic, the documentation offers a webhook mode, which reverses the connection direction so Telegram itself sends requests to the bot.

How do you keep strangers out of the bot?#

Your bot can be found in Telegram search by its username, so protection relies on two things: the access list and keeping the token secret.

First, configure sender access with TELEGRAM_ALLOWED_USERS. For groups, also inspect TELEGRAM_GROUP_ALLOWED_CHATS: listing a chat there permits any of its members, even when their sender ID is absent from the personal allowlist. An empty personal list alone therefore does not prove that every group is closed.

Second, there’s the token. It must not end up in screenshots, forwarded messages, or repositories. If the token leaks, revoke it with the /revoke command in BotFather. Then enter the new token in the settings and restart the gateway.

A separate note about groups: sender authorization and chat authorization are different. A member of a group permitted through TELEGRAM_GROUP_ALLOWED_CHATS can use the bot even if their ID is not in TELEGRAM_ALLOWED_USERS. If access must remain individual, do not grant the entire group access; configure and verify sender restrictions for your installed version. If you want the bot to respond in a group only when called, there’s a telegram.require_mention setting — then it responds to an @ mention, a reply to its message, a command like /command@yourbot, and matches for your patterns in telegram.mention_patterns, while ignoring ordinary group messages.

Why is the bot silent in a group, and how do you fix it?#

New Telegram bots have privacy mode enabled by default; Hermes documentation describes it as the most common source of confusion with bots in groups. In this mode, the bot receives only messages that start with a / command, replies to its own messages, and service notifications. It simply doesn’t receive ordinary group messages — Telegram doesn’t send them to it, and no agent setting will fix that.

How to fix it:

1. Open @BotFather and send /mybots.
2. Select your bot.
3. Open “Bot Settings” → “Group Privacy” → “Turn off.”
4. Remove the bot from the group and add it again.

It’s easy to miss the fourth step, and then the bot “still stays silent.” Telegram remembers the privacy setting from when the bot joined the group, and doesn’t update it until the bot is removed from the group and added again.

If you don’t want to disable privacy globally, there’s a second option: make the bot a group administrator. Admin bots receive all messages in any privacy mode.

Common connection errors and what to do about them#

What else do people ask about Hermes Agent in Telegram?#

When you’re ready, get to know Ailoot.