How do I get a Telegram bot token for Hermes?

The quickest way is Create with QR on the Messaging → Telegram page of the Hermes dashboard or desktop app: Hermes creates the bot, detects your user ID and writes both values to .env. Manually, message @BotFather, send /newbot, choose a name and a username ending in bot, and put the token in ~/.hermes/.env as TELEGRAM_BOT_TOKEN.

How do I stop strangers from using my Hermes Telegram bot?

Set TELEGRAM_ALLOWED_USERS in ~/.hermes/.env to your numeric user ID (from @userinfobot), comma-separated for several people. The Hermes gateway denies everyone who is not allowlisted, and denies everyone if no allowlist is configured. Never set GATEWAY_ALLOW_ALL_USERS=true.

Why does my Hermes bot reply in DMs but not in a group?

Usually Telegram privacy mode: disable it in BotFather with /setprivacy, then remove and re-add the bot to the group. Also check the sender is in TELEGRAM_ALLOWED_USERS (or allow the group with TELEGRAM_GROUP_ALLOWED_CHATS) and, if telegram.require_mention is true, that the message mentions or replies to the bot.

Last updated: 2026-09-27

Hermes Channel Setup: Telegram

Telegram is the fastest way to put Hermes in your pocket. Create a bot, give Hermes the token and your user ID, and you can hand work to your agent from anywhere while it runs on a server at home. Setup takes about five minutes, and locking the bot down so only you can command it takes no longer.

Quickest route (v0.21+): Create with QR

Open Messaging → Telegram in the web dashboard or desktop app and click Create with QR. Scan the code in Telegram: Hermes creates the bot, detects your user ID, writes TELEGRAM_BOT_TOKEN and TELEGRAM_ALLOWED_USERS into .env, and restarts the gateway. The manual steps below do the same thing by hand.

1. Create a bot with BotFather

In Telegram, open @BotFather (the official one, blue checkmark).
Send /newbot. Pick a display name (such as "My Hermes") and a username ending in bot.
BotFather replies with a token like 123456789:ABCdef…. Treat it like a password. Anyone who has it can act as your bot.

2. Find your user ID

Hermes allows people by their numeric Telegram ID, not their username. Message @userinfobot (or @get_id_bot) and it replies with your number, such as 123456789.

3. Configure Hermes

Either run the wizard and choose Telegram:

hermes gateway setup

or add both values to ~/.hermes/.env yourself:

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789        # comma-separated for more people

Then start the gateway, in the foreground to test or as a service for real use:

hermes gateway                 # foreground
hermes gateway install         # or: background service (systemd/launchd)
hermes gateway start

Test it both ways: message the bot from your account and it replies; have someone else message it and it should ignore them.

Deny-by-default, and keep it that way

With no allowlist configured, the gateway ignores everyone and logs a warning. Don't "fix" that with GATEWAY_ALLOW_ALL_USERS=true. Add IDs to TELEGRAM_ALLOWED_USERS, or use DM pairing: a stranger who messages the bot gets a code, and nothing happens until you run hermes pairing approve telegram <code>. If the token ever leaks, revoke it in BotFather (/revoke) and update .env. See the security guide.

4. Set a home channel for scheduled jobs

Send /sethome in the chat, DM or group, where cron job results should go. Or set TELEGRAM_HOME_CHANNEL in .env. Group IDs are negative numbers such as -1001234567890, and your DM chat ID is your user ID.

5. Running in a group

Let Telegram deliver the messages. Bots in groups only see commands and mentions unless privacy mode is off: in BotFather send /setprivacy → Disable. Then remove the bot from the group and add it again; Telegram keeps the old behaviour for existing members.

Make it mention-only, so it doesn't answer every message:

# ~/.hermes/config.yaml
telegram:
  require_mention: true          # reply only to @mentions, replies to the bot, /command@bot
  exclusive_bot_mentions: true   # with several Hermes bots, only the mentioned one answers
  mention_patterns:
    - "^\\s*hermes\\b"           # optional wake word, case-insensitive regex

Keep the allowlist. TELEGRAM_ALLOWED_USERS still applies in groups. To allow a whole group instead, use TELEGRAM_GROUP_ALLOWED_CHATS with the group's negative ID, or allow specific members with TELEGRAM_GROUP_ALLOWED_USERS.

Several Hermes bots in one group? Give each profile its own bot token. Two gateways polling one token will fight over messages.

Troubleshooting

No reply at all: check hermes gateway status, the token in .env, and that your numeric ID is in TELEGRAM_ALLOWED_USERS. A missing ID is the most common cause.
Works in DMs but not in the group: privacy mode (disable it, then remove and re-add the bot), then the allowlist, then require_mention.
Replies to everyone in the group: set telegram.require_mention: true.
Every new message continues an old conversation: that's by design. A Telegram chat is one continuous session. Send /new to start fresh; it also loads any new memories.

More fixes: Hermes troubleshooting. Voice notes, webhooks, large files and forum topics are covered in the official Telegram docs.