How to connect Hermes Agent to Telegram (step by step)

What you need first

• A Telegram account (download here if you don't have one — it's free)
• Hermes Agent installed (self-hosted or via Hermes OS, which handles Telegram setup through the dashboard)
• Your Telegram User ID — you'll get this in step 2

Step 1: Create your bot with BotFather

BotFather is Telegram's official tool for creating other bots. Open Telegram, search for @BotFather — it has a blue verified checkmark — and send it: /newbot

It asks for:

1. A name for your bot (display name, anything you like — 'My Hermes Agent')
2. A username (must end in bot, must be unique across Telegram — 'myhermesagent_bot')

Once created, BotFather sends your bot token. It looks like: 1234567890:AAFxxxxxxxxxxxxxxxxxx

Copy it somewhere safe.

Keep the bot token private. Anyone with this token controls your bot. Don't paste it into chat, don't commit it to a public repo, don't include it in screenshots.

If you think it's been compromised: BotFather → /mybots → select your bot → API Token → Revoke. Generates a new token instantly, invalidates the old one.

Step 2: Find your Telegram User ID

Your User ID is a number, not your @username. It's how Hermes knows which accounts to respond to.

Open Telegram, search for @userinfobot, and send it any message. It replies with your numeric User ID — something like 123456789.

If you want multiple people to use your bot, collect all their User IDs now.

This matters because without an allowlist, anyone who finds your bot can send it commands. Hermes has access to your server's filesystem and terminal. Setting the User ID allowlist is the main security step — everything else is configuration.

Step 3: Add credentials to Hermes

Open the Hermes environment file:

Add these two lines:

Multiple users:

Save (in nano: Ctrl+O → Enter → Ctrl+X). Or run the interactive wizard which handles all of this:

Step 4: Start the gateway

Test it first:

You should see output showing the Telegram listener started. Open Telegram, find your bot by username, send it something — 'Hello' or 'What can you do?'

If it responds, it's working. Press Ctrl+C to stop the test.

Now install it as a background service:

From this point the gateway runs in the background. Close the terminal. Messages sent to your bot on Telegram reach the agent, it runs the task, it replies.

If messages don't arrive

Bot doesn't respond at all:

• Check the gateway is running: hermes gateway status
• Verify the bot token is complete (no truncation, no trailing space)
• Confirm your User ID is in TELEGRAM_ALLOWED_USERS — it's a number, not your @username

Error: 'Unauthorized':

• Bot token is wrong or revoked. Check it in BotFather: /mybots → your bot → API Token.

Error: 'User not in allowlist':

• Your User ID isn't in the list. Double-check with @userinfobot that you got the right number.

Gateway starts then crashes:

• Check logs: journalctl --user -u hermes-gateway -f (Linux with systemd)
• Or: tail -f ~/.hermes/logs/gateway.log

Optional: use a dedicated phone number

If you already use Telegram bots for other things, consider creating a completely separate Telegram account just for Hermes. Separate phone number, separate identity.

Benefits: cleaner notification management, lower risk to your personal account, easier to share with colleagues. Not required for personal use — this is mainly worth it if you're running it for a team.

What to say to it

Once connected, just message it. Some starting points:

• 'What can you do?' — lists capabilities and installed skills
• 'Remember that my name is [name] and I work as a [role]' — seeds the memory file
• 'Check if google.com is reachable' — tests tool execution
• 'Send me a Telegram message every weekday at 8am with a brief weather summary for [city]' — sets up a scheduled task

For a broader look at what people use it for day to day: 12 real use cases here. For connecting other platforms alongside Telegram: the full gateway guide.

On Hermes OS

If you're using Hermes OS instead of self-hosting, Telegram setup is in the dashboard. Paste your bot token and User ID, click save. No SSH, no .env editing, no terminal.