How to Connect Hermes Agent to Telegram: Complete Setup Guide

Connecting Hermes Agent to Telegram takes five steps: create a bot through BotFather, get your user ID, run hermes gateway setup, paste your credentials, and start the gateway. Once connected, you can chat with your AI agent from any device, send voice memos that get auto-transcribed, receive scheduled task results, and use the agent in group chats — all through the Telegram messaging gateway built on python-telegram-bot.

Step 1: Create a Telegram Bot

Every Telegram bot requires an API token issued by @BotFather, Telegram's official bot management tool. The token is a long string that authenticates your bot with Telegram's servers.

Open Telegram and search for @BotFather. Start a conversation and follow these steps:

1. Send /newbot to BotFather
2. Enter a display name for your bot (e.g., "My Hermes Agent")
3. Enter a username ending in "bot" (e.g., "my_hermes_agent_bot")
4. BotFather responds with your bot token — a string like 7123456789:AAF...

Keep your bot token secret. Anyone with this token can control your bot, read messages, and impersonate it. Do not commit it to version control or share it in public channels.

If you have not installed Hermes Agent yet, follow our Hermes Agent installation guide first.

Step 2: Get Your Telegram User ID

Hermes Agent uses numeric Telegram user IDs — not usernames — to control who can interact with the bot. Your user ID is a number like 123456789 that never changes, even if you update your display name or @username.

The easiest method: message @userinfobot on Telegram. It instantly replies with your numeric user ID. Copy this number — you will need it in the next step.

For team deployments where multiple people need access, collect each team member's user ID using the same method.

Step 3: Configure the Hermes Gateway

The Hermes gateway is the service layer that connects your agent to external messaging platforms. Configuration takes about 30 seconds once you have your bot token and user ID ready.

Run the gateway setup command:

hermes gateway setup

The wizard presents a list of available platforms. Select Telegram and paste:

1. Your bot token (from BotFather)
2. Your numeric user ID (from @userinfobot)

For Docker deployments, you can also set these as environment variables in your docker-compose.yaml:

environment:
  - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}

The token and user ID are stored in ~/.hermes/.env on the host machine.

Step 4: Start the Gateway

Starting the Telegram gateway makes your bot live and ready to receive messages immediately.

hermes gateway start

Open Telegram, find your bot by its username, and send a test message. You should see a response from Hermes Agent within a few seconds, depending on your LLM provider's latency.

For persistent deployments on a VPS, use Docker Compose with restart: unless-stopped so the gateway automatically restarts after server reboots. See the Docker deployment documentation for the full configuration.

Verifying the Connection

If the bot does not respond, check these common issues:

• Wrong user ID: Verify your ID matches what @userinfobot shows — usernames and user IDs are different
• Token expired: Regenerate the token through BotFather if it was revoked
• No LLM configured: The gateway needs a working model provider — run hermes model to verify
• Port conflicts: Check logs with hermes gateway logs for network errors

Telegram Features and Capabilities

The Hermes Agent Telegram integration supports text, voice, images, file attachments, and inline buttons. As of April 2026, the integration is built on python-telegram-bot and includes several capabilities beyond basic text chat.

Voice memo transcription is particularly useful for mobile workflows — record a quick message while walking and the agent processes it as text. No extra setup is required beyond the base gateway configuration.

Group Chat Configuration

Hermes Agent supports Telegram group chats with mention-based gating, meaning the bot only responds when explicitly @mentioned in the group conversation.

To enable group chat support:

1. Open a conversation with @BotFather
2. Send /mybots and select your bot
3. Go to Bot Settings > Group Privacy
4. Set privacy mode to OFF

With privacy mode disabled, the bot receives every message in the group. Hermes Agent's gateway filters these and only processes messages that @mention the bot, keeping responses focused and avoiding noise.

For teams, configure multiple user IDs in the gateway config so each team member can interact with the bot. Each user gets their own conversation thread with shared agent memory — the agent remembers context across all users while keeping individual conversation histories separate.

For a comparison of how this approach differs from OpenClaw's Telegram integration, see our OpenClaw vs Hermes Agent comparison.

Limitations and Tradeoffs

The Telegram integration has several constraints to be aware of before deploying.

• Bot API rate limits. Telegram imposes rate limits on bot messages — approximately 30 messages per second globally and 1 message per second per chat. High-frequency automated responses may hit these limits.
• No end-to-end encryption. Telegram bot conversations are not end-to-end encrypted. Messages pass through Telegram's servers. Do not send sensitive credentials or confidential data through the bot.
• Response latency. Response time depends on your LLM provider. Cloud APIs like Anthropic or OpenAI typically respond in 2-10 seconds. Local models via Ollama may be slower depending on hardware.
• Voice transcription accuracy. Auto-transcription quality depends on the STT engine and audio clarity. Background noise, accents, and low-quality microphones can affect accuracy.
• Always-on requirement. The gateway must be running continuously to receive messages. If your server goes down, messages sent during downtime are queued by Telegram but may be missed if the queue exceeds Telegram's retention window.

Related Guides

• How to Install and Set Up Hermes Agent
• What Is Hermes Agent?
• OpenClaw Telegram Bot Setup
• Best AI Agents for Small Business

Frequently Asked Questions

Can Hermes Agent work in Telegram group chats?

Yes. Hermes Agent supports Telegram group chats with mention-gating — the bot only responds when explicitly @mentioned. You need to disable Telegram's bot privacy mode through BotFather so the bot can receive group messages. Each user in the group gets their own conversation thread while sharing the same agent instance.

Does Hermes Agent support Telegram voice messages?

Yes. Send a voice memo in Telegram and Hermes auto-transcribes it using Whisper or cloud speech-to-text with no extra configuration needed. The transcribed text is processed as a normal message, and the agent responds in text. This works in both private chats and group conversations.

Can I run Telegram and Discord on the same Hermes instance?

Yes. Multiple gateways can run simultaneously on a single Hermes Agent instance. Configure each gateway separately using hermes gateway setup, then start all of them with hermes gateway start. Each platform maintains its own conversation threads while sharing the same agent memory and skills.

How do I restrict who can use my Hermes Telegram bot?

Hermes Agent uses numeric Telegram user IDs for access control. During gateway setup, you enter your user ID (get it from @userinfobot on Telegram). Only users whose IDs are in the allowed list can interact with the bot. For team deployments, add multiple user IDs in the gateway configuration.

Is my Telegram bot token stored securely?

The bot token is stored in your Hermes configuration directory at ~/.hermes/.env. It is not transmitted anywhere except to Telegram's API. Keep this file secure — anyone with the token can control your bot. If the token is compromised, revoke it immediately through BotFather and generate a new one.