Connect Hermes Agent to Telegram
Run the Hermes Agent gateway and reach your AI from any device. Send voice memos, receive task results, use it in group chats — all through a Telegram bot you own.
What You Can Do
The Hermes Agent gateway connects your local agent to Telegram — everything it supports, in one place.
Chat from anywhere
Your Hermes agent runs on your machine. The Telegram bot is just the interface — works on phone, desktop, web, anywhere Telegram runs.
Voice memos
Send a voice message on Telegram. Hermes transcribes it automatically and responds in text (or voice, if TTS is configured).
Scheduled task delivery
Set a home channel, and Hermes delivers cron job results, reminders, and agent-triggered notifications directly to that chat.
Group chat support
Add the bot to a group. Control which users can trigger it, whether it responds to all messages or only mentions, and bind different skills to different topics.
Before You Start
Make sure you have these three things ready before running the setup wizard.
- ✓Hermes is installed and running→ /install
- ✓You have a working LLM configured→ /models
- ✓You have a Telegram account
The most common reason a bot doesn't respond isn't the bot — it's the model.
Telegram is just a message channel. If your LLM provider isn't configured or your API key has expired, the bot will receive your message and go completely silent. No error, no reply. Run hermes model to verify your current setup before proceeding.
Setup
Create a bot with BotFather
Every Telegram bot starts here. BotFather is Telegram's official bot management account — it issues the API token that connects Hermes to your bot.
- Open Telegram and message @BotFather
- Send /newbot
- Enter a display name (e.g., Hermes Agent) — visible to anyone who opens the bot
- Enter a username — must be unique and end in bot (e.g., my_hermes_bot)
- BotFather replies with your token:
Save this token. You'll need it in Step 3.
Find your Telegram User ID
Hermes uses numeric user IDs — not usernames — to control who can interact with your bot. Your user ID is a number like 123456789.
Message @userinfobot on Telegram. It replies instantly with your ID. Copy it.
Configure Hermes
Run the interactive setup wizard. It asks for your bot token and user IDs, then writes the configuration automatically.
Select Telegram when prompted. Enter the token from Step 1 and the user ID from Step 2.
Manual configuration (advanced)
If you prefer not to use the interactive wizard, edit ~/.hermes/.env directly:
Start the gateway
The bot comes online within a few seconds. You should see:
Send your bot a message on Telegram to verify. If it responds, you're done.
Using Hermes in a group chat? Read this first.
Telegram bots have Privacy Mode enabled by default. With Privacy Mode on, your bot can only see messages that start with / or are direct replies to the bot — it ignores everything else.
To fix this: go to BotFather → /mybots → select your bot → Bot Settings → Group Privacy → Turn off.
Critical: Critical: After changing this setting, you must remove the bot from the group and re-add it. Telegram caches the privacy state when a bot joins — it won't update until the bot rejoins.
Alternative: promote the bot to group admin. Admin bots always receive all messages regardless of the privacy setting.
Verify everything works
Send your bot these messages to confirm each layer is working:
| Message | Expected result |
|---|---|
Hello | Agent replies in text |
| A voice memo | Agent transcribes and replies |
/model | Shows current model + interactive picker |
/sethome | Confirms this chat as the home channel for scheduled tasks |
If Hello gets no reply, go to the FAQ section below.
FAQ
My bot receives messages but never replies
Cause A — Model not configured or API key expired
This is the most common cause. Telegram delivers the message to Hermes, but Hermes can't generate a reply because the LLM isn't available.
If your API key ran out of credits or expired, the failure is completely silent — no error message, no log entry at the Telegram level. Check your provider dashboard directly. This affects OpenRouter, OpenAI, Anthropic, and all other providers equally.
Cause B — Bot token is wrong
Verify the token matches what BotFather issued. If you accidentally regenerated it, update the .env file and restart the gateway.
Bot says unauthorized when I message it
Your Telegram user ID is not in TELEGRAM_ALLOWED_USERS.
Verify your numeric user ID is listed. Get it again from @userinfobot if needed. After editing .env, restart the gateway.
Bot works in DMs but ignores group messages
Privacy Mode is on. Short version:
BotFather → /mybots → your bot → Bot Settings → Group Privacy → Turn off → remove bot from group → re-add bot.
See the Warning in Step 4 above for the full explanation.
Voice messages aren't being transcribed
Hermes needs a speech-to-text provider configured. The default local option uses faster-whisper:
Or set a cloud provider in ~/.hermes/.env:
Voice replies come through as audio files, not voice bubbles
This happens with Edge TTS (the default free TTS provider). It outputs MP3, which requires ffmpeg to convert to Opus before Telegram can display it as a voice bubble.
Without ffmpeg, audio is still delivered — it just uses the rectangular player instead of the round voice bubble.
I'm deploying to a cloud server — do I need webhook mode?
Yes, for cloud deployments. The default polling mode keeps an outbound connection open at all times, which prevents the machine from sleeping. Webhook mode lets Telegram push updates to your server, so the machine can sleep between messages.
Full Fly.io deployment instructions are in the official docs ↗.
Advanced
Optional configuration for power users. Read what's relevant to your setup.
Group chat mention control
By default, Hermes responds to every message it can see in a group. To restrict it to direct mentions and commands only:
With this config, the bot responds to /commands, @botusername mentions, direct replies, and any message matching your patterns.
Private Chat Topics
Bot API 9.4 lets bots create forum-style topic threads inside 1-on-1 DM chats. Each topic gets its own isolated session, history, and context.
Hermes creates the topics on startup and saves the thread_id back to config automatically.
Message reactions
Enable emoji reactions as processing feedback — while thinking, on success, on error:
Or via env var: TELEGRAM_REACTIONS=true
Restricted network / proxy
If api.telegram.org is unreachable on your network, Hermes automatically tries DNS-over-HTTPS fallback IPs. If you need an explicit proxy:
No additional config needed — the gateway reads standard proxy environment variables automatically.
This guide covers Hermes Agent Telegram setup. The same gateway also supports Discord, Slack, WhatsApp, and Signal. For webhook deployment, group forum topic skill binding, and the full configuration reference, see the official documentation.