How to connect Hermes Agent to Telegram

Short answer. Create a bot with @BotFather in Telegram (/newbot) and copy its token. Give Hermes Agent the token and your numeric Telegram user ID: only the IDs on its allowlist, or people you approve with a pairing code, can talk to it; with no allowlist, a stranger gets nothing but a pairing code you would have to approve. On your own machine that is TELEGRAM_BOT_TOKEN and TELEGRAM_ALLOWED_USERS in ~/.hermes/.env, or hermes gateway setup. On PlayNHost you paste the token and your ID on the Agent page and restart.

Checked on 7 November 2026, accurate for Hermes Agent v0.23.0.

This guide uses Hermes Agent's Telegram and security documentation and the PlayNHost panel as it works today. Telegram support is built into Hermes Agent's messaging gateway: there is nothing extra to install.

Step 1: create the bot and copy its token

1. In Telegram, open a chat with @BotFather (or t.me/BotFather). Check that the handle is exactly @BotFather.
2. Send /newbot, choose a display name, then a username that ends in bot.
3. BotFather replies with the token, which looks like 123456789:ABCdefGHIjklMNOpqrSTUvwxYZ. Keep it private: anyone with it can control your bot. If it leaks, revoke it with /revoke in BotFather.

One program per bot. Hermes Agent's FAQ says each chat platform needs exclusive use of a bot token. If an older copy of Hermes Agent, or any other program, still uses the same token, stop it first or create a new bot.

Step 2: find your Telegram user ID

Hermes Agent's allowlist takes your numeric user ID, a number like 123456789, not your @username. Ways to get it:

• On PlayNHost, from the console. Message your bot before you have set any ID: the console prints your ID. Details in Step 3 below.
• From Hermes Agent's log. When someone not on its list sends a direct message, its log (~/.hermes/logs/gateway.log) gets a warning starting "Unauthorized user" with the sender's numeric ID (in brackets after their name when strangers are set to be ignored, as on PlayNHost).
• A third-party bot. Hermes Agent's docs suggest @userinfobot or @get_id_bot, which reply with your ID.

Step 3 on PlayNHost: paste the token and your ID

You need an AI provider key on the same page. Without one, Start stops with "Your agent is not set up yet: it needs an API key from one AI provider and a Telegram or Discord bot token."

1. Open your server at panel.playnhost.com, then the Agent tab.
2. Under AI provider, set one key if you have not yet (see which AI provider key to use).
3. Under Chat apps, press Set on Telegram bot token, paste the token from BotFather and press Save. The panel checks its shape; a wrong paste gets "That is not a valid telegram bot token." Once saved, the row shows only the last four characters, and the token is never shown again.
4. Don't know your ID yet? Leave Telegram user IDs empty and press Start. The first start installs Hermes Agent, which took about 2.5 to 4 minutes in our tests. When the agent is up, the console prints:

   [PlayNHost] Your agent is running
   [PlayNHost] Telegram: nobody can message your agent yet. Send your bot any message: your Telegram user ID appears here in the console. Put it on the Agent page, then restart.

   Send your bot a message in Telegram. It does not answer, not even with a pairing code: on PlayNHost, Hermes Agent ignores anyone who is not on the list. Within about 20 seconds (the console checks Hermes Agent's log every 20 seconds) it shows your ID:

   [PlayNHost] Telegram user 123456789 messaged your agent and was ignored. If that is you, add 123456789 to the Telegram user IDs on the Agent page, then restart.

5. Under Who can message it, type the number into Telegram user IDs and press Save. Several IDs go on one line, separated by commas or spaces.
6. The page says "Changes apply the next time your agent starts." Press Restart now. The console then confirms:

   [PlayNHost] Telegram: only user 123456789 can message your agent.

7. Message your bot. Your agent answers. Messages from any other Telegram account are ignored, and each new sender who messages the bot directly appears in the console once per start, so you can add a friend the same way.

What PlayNHost sets for you

• The IDs on the Agent page reach Hermes Agent as TELEGRAM_ALLOWED_USERS. Every other way to let people in (allow-all switches, other allowlists, group grants, pairing approvals) is switched off at each start, and the agent is stopped if one appears while it runs.
• Strangers are ignored (unauthorized_dm_behavior: ignore) instead of getting Hermes Agent's default pairing code, because a PlayNHost server has no command line to approve a code with.
• The token reaches Hermes Agent as TELEGRAM_BOT_TOKEN. A copy of it written into .hermes/.env is removed at the next start, so the token on the Agent page is the one used.
• Only Telegram and Discord are on. WhatsApp is refused: Hermes Agent's own docs say its WhatsApp bridge emulates a WhatsApp Web session and carries a ban risk.

Step 3 on your own machine

1. Run the setup wizard and choose Telegram. It asks for the token and the allowed user IDs and writes them for you:

   hermes gateway setup

2. Or add them by hand to ~/.hermes/.env:

   TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
   TELEGRAM_ALLOWED_USERS=123456789

   Several IDs are comma-separated.
3. Start the gateway with hermes gateway and send your bot a message. To keep it running after you log out, see how to run Hermes Agent 24/7.

Without any allowlist, Hermes Agent denies everybody. Its default for strangers is a pairing code that you approve with hermes pairing approve telegram <code>; codes expire after one hour. Hermes Agent's docs also offer GATEWAY_ALLOW_ALL_USERS=true, and warn against it for a bot that can run commands.

When it does not answer

On PlayNHost, Hermes Agent's own log is .hermes/logs/gateway.log in Files. Want Discord as well? See connect Hermes Agent to Discord. Not set up yet? Create a Hermes Agent server.

PlayNHost is not affiliated with Nous Research. Hermes Agent is open-source software under the MIT licence.