Setting Up Hermes as a Telegram Bot
Turning Hermes Agent into a Telegram bot is one of the quickest ways to get hands-free, on-the-go access to your agent. Since Hermes already ships a messaging gateway that covers 21+ platforms, Telegram is configured through the same setup flow as every other messenger — install the extras, add your bot credentials, and start the gateway. From there, you chat with the full agent — its tools, memory, skills, and cron jobs — from the Telegram app on any device.
The official docs include a dedicated Telegram setup guide, and there's even a step-by-step tutorial for building a team Telegram assistant the whole team can use for code help, research, and system administration. Both ride on the same underlying gateway.
Install the Messaging Extras
Before Telegram works, the gateway package needs the messaging dependencies. In your ~/.hermes/hermes-agent checkout, install the messaging extra, which bundles the Python libraries Telegram needs:
cd ~/.hermes/hermes-agent && uv pip install -e ".[messaging]"
This installs python-telegram-bot and aiohttp alongside the other platform adapters. If you plan to use voice replies over Telegram, the same extra covers them — the [messaging] set already includes the audio plumbing needed for spoken responses.
Configure and Start the Gateway
With the package installed, the fast path is the interactive setup wizard:
hermes gateway setup # interactive wizard for first-time configuration
The wizard walks you through pairing each platform you want, including Telegram. Once configured, start the gateway:
hermes gateway # start the gateway (connects to configured platforms)
The bot should come online in Telegram within a few seconds. From there it behaves like any other Hermes surface — same sessions, tools, memory, skills, and slash commands as the CLI, all reachable from within Telegram.
Getting More From the Bot
Telegram isn't just text. Voice replies are a standout feature: when enabled, the agent sends spoken audio alongside text responses, delivered as a native Voice bubble (Opus/OGG) that plays inline in the chat. If a reply is generated as MP3, ffmpeg converts it to Opus first so Telegram can play it.
The voice mode commands work directly inside a Telegram chat with the bot:
/voice— toggle voice mode on/off/voice on— speak replies only when you send a voice message/voice tts— speak replies to every message/voice off— disable voice replies/voice status— show the current setting
The setting persists across gateway restarts, so you don't have to re-enable it when the gateway comes back up.
Putting the Bot to Work
Because the Telegram bot is the same agent, it plugs into the rest of Hermes. Cron jobs deliver their results straight into the chat — a daily briefing bot can research topics, summarize findings, and deliver a written (or spoken) summary to Telegram every morning. Scripts and monitoring can push output to the chat with hermes send. For a team, follow the Team Telegram Assistant guide to stand up a shared bot your colleagues use for code help, research, and admin — all with one agent underneath.
Key Takeaways
- Install the messaging extra with
uv pip install -e ".[messaging]"(includespython-telegram-botandaiohttp). - Configure with
hermes gateway setupand start withhermes gateway; the bot comes online in Telegram within seconds. - Voice replies arrive as native Telegram Voice bubbles (Opus/OGG), with
/voice,/voice on,/voice tts,/voice off, and/voice statuscontrolling spoken output. - The Telegram bot is the full agent — cron jobs and
hermes sendcan push output into the chat, and a team-facing bot takes the same setup.