Hermes Agent Telegram setup

Connect Hermes Agent to Telegram in ten minutes: create the bot with BotFather, allowlist your user ID, start the gateway, and fix the common group chat and voice issues.

Telegram is the most popular way to talk to Hermes from anywhere: full conversations from your phone, voice memos that get auto-transcribed, scheduled task results pushed to you, and group chat support. The setup takes about ten minutes. You need a working Hermes install first; see how to install Hermes.

1. Create the bot with BotFather

  1. In Telegram, open @BotFather (or visit t.me/BotFather).
  2. Send /newbot.
  3. Pick a display name, like "Hermes Agent".
  4. Pick a unique username ending in bot, like my_hermes_bot.
  5. BotFather replies with your API token, in the format 123456789:ABCdefGHIjklMNOpqrSTUvwxYZ.

Keep the token secret. Anyone who has it can control your bot.

2. Find your numeric user ID

Hermes controls access by numeric Telegram user ID, not username. Message @userinfobot and it replies with your ID (a number like 123456789). @get_id_bot works too.

3. Configure Hermes

The interactive wizard is the recommended path:

hermes gateway setup

Select Telegram when prompted; the wizard asks for your bot token and allowed user IDs and writes the config for you.

Manual alternative: add to ~/.hermes/.env:

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789

Multiple users are comma-separated: TELEGRAM_ALLOWED_USERS=123456789,987654321.

4. Start the gateway

hermes gateway

The bot comes online within seconds. Send it a message on Telegram to confirm.

Group chats

By default Telegram bots only see / commands and direct replies (privacy mode). To let Hermes participate fully in a group:

  1. Message @BotFather, send /mybots, select your bot.
  2. Bot Settings → Group Privacy → Turn off.
  3. Remove and re-add the bot to the group. Telegram caches the privacy setting, so this step is not optional.

Alternatively, promote the bot to group admin; admin bots receive all messages regardless of the privacy setting.

To control who can invoke the bot in groups:

TELEGRAM_GROUP_ALLOWED_USERS=987654321
TELEGRAM_GROUP_ALLOWED_CHATS=-1001234567890

Or require an explicit mention in config.yaml:

telegram:
  require_mention: true

Voice messages

Incoming voice memos are transcribed by your configured STT provider (local via faster-whisper, groq, or openai) and injected as text. Outgoing audio replies arrive as Telegram voice bubbles; if you use Edge TTS, install ffmpeg (brew install ffmpeg on macOS, sudo apt install ffmpeg on Ubuntu/Debian) for Opus conversion.

Troubleshooting

| Problem | Fix | | --- | --- | | Bot not responding | Verify the token; check hermes gateway logs | | "Unauthorized" error | Your numeric ID is missing from TELEGRAM_ALLOWED_USERS; confirm it with @userinfobot | | Ignores group messages | Disable privacy mode and rejoin the group, or make the bot a group admin | | Voice not transcribed | Install an STT provider: faster-whisper, GROQ_API_KEY, or VOICE_TOOLS_OPENAI_KEY | | Voice replies arrive as files | Install ffmpeg for Edge TTS Opus conversion | | Invalid token | Revoke with /revoke and regenerate via BotFather |

Source: Hermes Agent Telegram docs, checked June 2026.

Share:
Explore HermesInstallation