Connect Hermes Agent to Telegram: Complete Guide

Connect Hermes Agent to Telegram: Complete Guide

Telegram has become much more than a simple messaging app. With its powerful bot API, media support, topic-based groups, and voice messages, it's the ideal companion for interacting with Hermes Agent — wherever you are, from your phone, tablet, or desktop.

In this comprehensive guide, we cover everything from creating the bot to deploying 24/7, including security, multi-group management, and real-world use cases.

Why Telegram Is the Best Companion for Hermes

Hermes Agent shines in a terminal, but not everyone has a terminal handy at all times. Telegram bridges this gap with unique advantages:

• Available everywhere: mobile, desktop, web — one synchronized conversation
• Voice messages: send a voice memo, Hermes auto-transcribes via Whisper (local, Groq, or OpenAI)
• Media support: images, PDFs, files — all handled natively via the MEDIA: system
• Topic groups (forum): each topic = an isolated session with its own context
• Mature Bot API: webhooks, inline keyboards, reactions, streaming — everything works
• Open source: Telegram's client is open source, the API is well-documented and free

💡 Analogy: if the terminal is the agent's "office desk", Telegram is its "mobile phone" — always on, always reachable.

Create a Telegram Bot via @BotFather

The entire Telegram infrastructure relies on an official bot. Here's how to create one in 5 minutes.

Step 1: Get the token

1. Open Telegram and search for @BotFather
2. Send /newbot
3. Choose a display name (e.g., "My Hermes Agent")
4. Choose a unique username ending in bot (e.g., my_hermes_bot)
5. BotFather replies with your API token:

123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

⚠️ Security: keep this token secret. Anyone with it can control your bot. If it leaks, revoke immediately via /revoke in BotFather.

Step 2: Customize the bot (optional)

Improve the user experience with these BotFather commands:

• /setdescription: text shown before the first message
• /setabouttext: short description on the profile
• /setuserpic: bot avatar
• /setcommands: command menu (the / button in chat)

For /setcommands, a good starting point:

help - Show help information
new - Start a new conversation
sethome - Set this chat as home channel
model - Switch AI model
reset - Reset session

Step 3: Find your User ID

Hermes uses numeric IDs for access control. This is NOT your username — it's a number like 123456789.

Send a message to @userinfobot or @get_id_bot. Note this number.

Configure Hermes with hermes gateway setup

Hermes provides an interactive wizard for Telegram configuration.

Interactive method (recommended)

hermes gateway setup

Select Telegram from the menu. The wizard asks for:

1. Your bot token (from BotFather)
2. Your allowed user IDs (comma-separated)
3. It writes the configuration automatically

Manual method

Add directly to ~/.hermes/.env:

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789

For multiple users:

TELEGRAM_ALLOWED_USERS=123456789,987654321

Start the gateway

hermes gateway

The bot should come online within seconds. Send it a message to verify.

Conversation Modes

Hermes Agent via Telegram supports three conversation modes, each with specific features.

Private mode (DM)

The simplest mode. You chat directly with the bot. Each DM conversation gets its own session with history, context, and persistent memory.

Group mode

Hermes also works in Telegram groups, but requires special attention to privacy mode.

Privacy mode ON (default): the bot only sees:
- Messages starting with /
- Replies to its own messages
- Messages in channels where it's an admin

Privacy mode OFF: the bot receives all group messages.

To disable privacy mode:
1. Message @BotFather
2. /mybots → select your bot
3. Bot Settings → Group Privacy → Turn off

⚠️ Important: after changing privacy mode, you must remove and re-add the bot to the group. Telegram caches the privacy state when a bot joins.

Alternative: promote the bot to group admin. Admins see all messages regardless of privacy mode.

Topic mode (forum)

Telegram Bot API 9.4 (February 2026) introduced Private Chat Topics — forum-style topics directly in DMs. Each topic = an isolated session.

Example configuration in ~/.hermes/config.yaml:

platforms:
  telegram:
    extra:
      dm_topics:
      - chat_id: 123456789
        topics:
        - name: General
          icon_color: 7322096
        - name: Website
          icon_color: 9367192
        - name: Research
          icon_color: 16766590
          skill: arxiv

💡 The skill field automatically loads a skill in the topic. Here, the "Research" topic loads the arxiv skill on each new session.

Managing Multiple Groups and Channels

Hermes can simultaneously manage multiple Telegram groups and channels.

Mention-based control

To prevent the bot from responding to everything in an active group:

telegram:
  require_mention: true
  mention_patterns:
    - "^\s*hermes\b"
  ignored_threads:
    - 31
    - "42"

The bot responds when:
- A / command is used
- Someone replies to one of its messages
- It's mentioned with @botusername
- The message matches a pattern (here, starts with "hermes")

Topics 31 and 42 are always ignored.

Group allowlist

gateway:
  platforms:
    telegram:
      extra:
        group_allowed_chats:
          - "-1001234567890"
        group_allow_from:
          - "987654321"

• group_allowed_chats: all members of these groups are authorized
• group_allow_from: only these specific users can trigger the bot in groups (no DM access)

Home channel for scheduled tasks

Use /sethome in any chat to designate it as the main channel. Cron job results are delivered there.

Manual configuration:

TELEGRAM_HOME_CHANNEL=-1001234567890
TELEGRAM_HOME_CHANNEL_NAME="My Notes"

💡 Group IDs are negative numbers (e.g., -1001234567890). Your DM chat ID equals your user ID.

Slash Commands from Telegram

From Telegram, you have several built-in commands:

• /help — show help
• /new — start a new conversation
• /reset — reset current session
• /model — switch AI model (interactive picker)
• /model <name> — switch model directly
• /model <name> --global — persist the change across sessions
• /sethome — set home channel
• /skill-name — load a skill (same as in terminal)

The interactive model picker displays inline buttons with paginated navigation between providers and models — everything happens in the same message, no chat clutter.

File and Media Delivery

Hermes uses the MEDIA: system for sending files via Telegram. The gateway detects MEDIA:/path/to/file tags in agent responses and sends them as native attachments.

Supported extensions

• Images: png, jpg, jpeg, gif, webp, bmp, tiff, svg
• Audio: mp3, wav, ogg, m4a, opus, flac, aac
• Video: mp4, mov, webm, mkv, avi
• Documents: pdf, txt, md, csv, json, xml, html, yaml, yml, log
• Office: docx, xlsx, pptx, odt, ods, odp
• Archives: zip, rar, 7z, tar, gz, bz2

Docker pitfall

If your terminal backend is Docker, files generated inside the container aren't accessible to the host-running gateway. Solution:

terminal:
  backend: docker
  docker_volumes:
    - "/home/user/.hermes/cache/documents:/output"

Then the agent writes to /output/... inside Docker and emits the host path in MEDIA:.

Voice messages

• Incoming: automatically transcribed via Whisper (local, Groq, or OpenAI)
• Outgoing: TTS responses delivered as native Telegram voice bubbles
• Edge TTS requires ffmpeg for Opus conversion: sudo apt install ffmpeg

Markdown Formatting in Telegram

Telegram uses its own MarkdownV2 format, but Hermes normalizes rendering automatically:

• Small tables → converted to bulleted row-group lists
• Wide tables → code blocks with aligned columns
• Link previews → can be disabled via disable_link_previews: true

telegram:
  pretty_tables: true  # enabled by default

Security: Allowlists and Access Restriction

Security is paramount when your AI agent is exposed on Telegram.

Security layers

1. TELEGRAM_ALLOWED_USERS: only these users can use the bot (DMs + groups)
2. TELEGRAM_GROUP_ALLOWED_USERS: group-specific permissions (no DM access)
3. TELEGRAM_GROUP_ALLOWED_CHATS: all members of these groups are authorized
4. require_mention: bot only responds on explicit mention
5. mention_patterns: regex patterns to trigger the bot
6. Exec Approval: dangerous commands require confirmation ("yes"/"no")

Secure configuration example

TELEGRAM_ALLOWED_USERS=123456789
TELEGRAM_GROUP_ALLOWED_CHATS=-1001234567890
TELEGRAM_REACTIONS=true

telegram:
  require_mention: true
  reactions: true

Reactions (👀 → ✅/❌) provide visual feedback on message processing.

Disable link previews

To prevent information leaks via previews:

gateway:
  platforms:
    telegram:
      extra:
        disable_link_previews: true

Message Queue Management

Hermes processes messages sequentially per session. When you send multiple messages quickly, they're queued and processed in order. Each session (DM, topic, group) has its own queue.

For high-load deployments, Hermes supports webhook mode — Telegram pushes updates to your HTTPS URL instead of continuous polling:

TELEGRAM_WEBHOOK_URL=https://my-app.fly.dev/telegram
TELEGRAM_WEBHOOK_SECRET="$(openssl rand -hex 32)"

Webhook mode is ideal for cloud platforms (Fly.io, Railway, Render) with auto-wake — the machine can sleep between messages.

Real-World Use Cases

1. Technical support bot

Configure Hermes in a support group with a dedicated skill:

platforms:
  telegram:
    extra:
      group_topics:
      - chat_id: -1001234567890
        topics:
        - name: Support
          thread_id: 5
          skill: customer-support

Hermes automatically answers technical questions with your documentation context.

2. Automated monitoring

Combine the home channel with scheduled tasks:

TELEGRAM_HOME_CHANNEL=-1001234567890

Set up a cron job in Hermes for daily tech news summaries delivered to your Telegram channel.

3. Personal multi-project assistant

Use DM topics to separate your projects:

• Topic "Dev" with software-development skill — code discussions
• Topic "Writing" — article and content writing
• Topic "Admin" — system management and DevOps

Each topic has its isolated session, history, and context.

4. Team automation

A shared group with chat-based allowlist — all team members interact with the agent without individual configuration:

group_allowed_chats:
  - "-1001234567890"

Deploy 24/7 with systemd

To keep your Telegram gateway running permanently on a VPS, use systemd.

💡 Hosting: for a reliable and affordable VPS, we recommend Hostinger — excellent performance for running AI agents.

systemd service

Create /etc/systemd/system/hermes-gateway.service:

[Unit]
Description=Hermes Agent Gateway (Telegram)
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=hermes
WorkingDirectory=/home/hermes
ExecStart=/usr/local/bin/hermes gateway
Restart=always
RestartSec=10
Environment=PATH=/usr/local/bin:/usr/bin:/bin

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable hermes-gateway
sudo systemctl start hermes-gateway
sudo systemctl status hermes-gateway

Real-time logs:

journalctl -u hermes-gateway -f

Common Troubleshooting

Conclusion

Connecting Hermes Agent to Telegram transforms your AI agent from a terminal tool into a personal assistant accessible everywhere. Configuration takes under 5 minutes, and the possibilities are vast: private DMs, collaborative groups, project-isolated topics, voice messages, native file delivery, and 24/7 deployment via systemd.

Security layers (allowlists, require_mention, exec approval) ensure that only authorized personnel interact with the agent, even in public groups.

To go further, explore the Skills system for loading specialized skills automatically in each topic, persistent memory so the agent remembers your preferences, or context files to customize behavior per project.

And if you're new to Hermes, our complete overview will guide you through installation and initial configuration.