Telegram Setup

Hermes Agent integrates with Telegram as a full-featured conversational bot. Once connected, you can chat with your agent from any device, send voice memos that get auto-transcribed, receive scheduled task results, and use the agent in group chats. The integration is built on python-telegram-bot and supports text, voice, images, and file attachments.

Step 1: Create a Bot via BotFather

Every Telegram bot requires an API token issued by @BotFather, Telegram's official bot management tool.

1. Open Telegram and search for @BotFather, or visit t.me/BotFather

2. Send /newbot

3. Choose a display name (e.g., "Hermes Agent") — this can be anything

4. Choose a username — this must be unique and end in bot (e.g., my_hermes_bot)

5. BotFather replies with your API token. It looks like this:

123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

Step 2: Customize Your Bot (Optional)

These BotFather commands improve the user experience. Message @BotFather and use:

help - Show help information
new - Start a new conversation
sethome - Set this chat as the home channel

Step 3: Privacy Mode (Critical for Groups)

Telegram bots have a privacy mode that is enabled by default. This is the single most common source of confusion when using bots in groups.

With privacy mode ON, your bot can only see:

• Messages that start with a / command

• Replies directly to the bot's own messages

• Service messages (member joins/leaves, pinned messages, etc.)

• Messages in channels where the bot is an admin

With privacy mode OFF, the bot receives every message in the group.

How to disable privacy mode

1. Message @BotFather

2. Send /mybots

3. Select your bot

4. Go to Bot Settings → Group Privacy → Turn off

Step 4: Find Your User ID

Hermes Agent uses numeric Telegram user IDs to control access. Your user ID is not your username — it's a number like 123456789.

Method 1 (recommended): Message @userinfobot — it instantly replies with your user ID.

Method 2: Message @get_id_bot — another reliable option.

Save this number; you'll need it for the next step.

Step 5: Configure Hermes

Option A: Interactive Setup (Recommended)

hermes gateway setup

Select Telegram when prompted. The wizard asks for your bot token and allowed user IDs, then writes the configuration for you.

Option B: Manual Configuration

Add the following to ~/.hermes/.env:

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789    # Comma-separated for multiple users

Start the Gateway

hermes gateway

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

Sending Generated Files from Docker-backed Terminals

If your terminal backend is docker, keep in mind that Telegram attachments are sent by the gateway process, not from inside the container. That means the final MEDIA:/... path must be readable on the host where the gateway is running.

Common pitfall:

• the agent writes a file inside Docker to /workspace/report.txt

• the model emits MEDIA:/workspace/report.txt

• Telegram delivery fails because /workspace/report.txt only exists inside the container, not on the host

Recommended pattern:

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

Then:

• write files inside Docker to /output/...

• emit the host-visible path in MEDIA:, for example: MEDIA:/home/user/.hermes/cache/documents/report.txt

If you already have a docker_volumes: section, add the new mount to the same list. YAML duplicate keys silently override earlier ones.

Supported MEDIA: file extensions

The gateway extracts MEDIA:/path/to/file tags from agent replies and ships the referenced file as a platform-native attachment. Supported extensions across all gateway platforms:

Anything on this list delivered as a native attachment on platforms that support it (Telegram, Discord, Signal, Slack, WhatsApp, Feishu, Matrix, etc.); on platforms without native support it falls back to a link or plain-text indicator. The bold categories were added in the last few releases — if you were relying on the model saying here is the file: /path/to/report.docx instead, swap to MEDIA:/path/to/report.docx for native delivery.

Webhook Mode

By default, Hermes connects to Telegram using long polling — the gateway makes outbound requests to Telegram's servers to fetch new updates. This works well for local and always-on deployments.

For cloud deployments (Fly.io, Railway, Render, etc.), webhook mode is more cost-effective. These platforms can auto-wake suspended machines on inbound HTTP traffic, but not on outbound connections. Since polling is outbound, a polling bot can never sleep. Webhook mode flips the direction — Telegram pushes updates to your bot's HTTPS URL, enabling sleep-when-idle deployments.

Configuration

Add the following to ~/.hermes/.env:

TELEGRAM_WEBHOOK_URL=https://my-app.fly.dev/telegram
TELEGRAM_WEBHOOK_SECRET="$(openssl rand -hex 32)"  # required
# TELEGRAM_WEBHOOK_PORT=8443        # optional, default 8443

When TELEGRAM_WEBHOOK_URL is set, the gateway starts an HTTP webhook server instead of polling. When unset, polling mode is used — no behavior change from previous versions.

Cloud deployment example (Fly.io)

1. Add the env vars to your Fly.io app secrets:

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

1. Expose the webhook port in your fly.toml:

[[services]]
  internal_port = 8443
  protocol = "tcp"

  [[services.ports]]
    handlers = ["tls", "http"]
    port = 443

1. Deploy:

fly deploy

The gateway log should show: [telegram] Connected to Telegram (webhook mode).

Proxy Support

If Telegram's API is blocked or you need to route traffic through a proxy, set a Telegram-specific proxy URL. This takes priority over the generic HTTPS_PROXY / HTTP_PROXY env vars.

Option 1: config.yaml (recommended)

telegram:
  proxy_url: "socks5://127.0.0.1:1080"

Option 2: environment variable

TELEGRAM_PROXY=socks5://127.0.0.1:1080

Supported schemes: http://, https://, socks5://.

The proxy applies to both the main Telegram connection and the fallback IP transport. If no Telegram-specific proxy is set, the gateway falls back to HTTPS_PROXY / HTTP_PROXY / ALL_PROXY (or macOS system proxy auto-detection).

Home Channel

Use the /sethome command in any Telegram chat (DM or group) to designate it as the home channel. Scheduled tasks (cron jobs) deliver their results to this channel.

You can also set it manually in ~/.hermes/.env:

TELEGRAM_HOME_CHANNEL=-1001234567890
TELEGRAM_HOME_CHANNEL_NAME="My Notes"

Voice Messages

Incoming Voice (Speech-to-Text)

Voice messages you send on Telegram are automatically transcribed by Hermes's configured STT provider and injected as text into the conversation.

• local uses faster-whisper on the machine running Hermes — no API key required

• groq uses Groq Whisper and requires GROQ_API_KEY

• openai uses OpenAI Whisper and requires VOICE_TOOLS_OPENAI_KEY

Outgoing Voice (Text-to-Speech)

When the agent generates audio via TTS, it's delivered as native Telegram voice bubbles — the round, inline-playable kind.

• OpenAI and ElevenLabs produce Opus natively — no extra setup needed

• Edge TTS (the default free provider) outputs MP3 and requires ffmpeg to convert to Opus:

# Ubuntu/Debian
sudo apt install ffmpeg

# macOS
brew install ffmpeg

Without ffmpeg, Edge TTS audio is sent as a regular audio file (still playable, but uses the rectangular player instead of a voice bubble).

Configure the TTS provider in your config.yaml under the tts.provider key.

Group Chat Usage

Hermes Agent works in Telegram group chats with a few considerations:

• Privacy mode determines what messages the bot can see (see Step 3)

• TELEGRAM_ALLOWED_USERS still applies — only authorized users can trigger the bot, even in groups

• You can keep the bot from responding to ordinary group chatter with telegram.require_mention: true

• With telegram.require_mention: true, group messages are accepted when they are:

• replies to one of the bot's messages
• @botusername mentions
• /command@botusername (Telegram's bot-menu command form that includes the bot name)

• matches for one of your configured regex wake words in telegram.mention_patterns

• Use telegram.ignored_threads to keep Hermes silent in specific Telegram forum topics, even when the group would otherwise allow free responses or mention-triggered replies

• If telegram.require_mention is left unset or false, Hermes keeps the previous open-group behavior and responds to normal group messages it can see

Troubleshooting: works in DMs but not groups

If the bot responds in a private chat but stays silent in a group, check these gates in order:

1. Telegram delivery: turn off BotFather privacy mode, promote the bot to admin, or mention the bot directly. Hermes cannot respond to group messages that Telegram never delivers to the bot.

2. Rejoin after changing privacy: remove the bot from the group and add it again after changing BotFather privacy settings. Telegram may keep the old delivery behavior for existing memberships.

3. Hermes authorization: make sure the sender is listed in TELEGRAM_ALLOWED_USERS or TELEGRAM_GROUP_ALLOWED_USERS, or allow the group chat with TELEGRAM_GROUP_ALLOWED_CHATS.

4. Mention filters: if telegram.require_mention: true is set, normal group chatter is ignored unless the message is a slash command, reply to the bot, @botusername mention, or configured mention_patterns match.

Negative chat IDs are normal for Telegram groups and supergroups. If you use chat-scoped authorization, put those IDs in TELEGRAM_GROUP_ALLOWED_CHATS, not the sender-user allowlist.

Example group trigger configuration

Add this to ~/.hermes/config.yaml:

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

This example allows all the usual direct triggers plus messages that begin with chompy, even if they do not use an @mention. Messages in Telegram topics 31 and 42 are always ignored before the mention and free-response checks run.

Notes on mention_patterns

• Patterns use Python regular expressions

• Matching is case-insensitive

• Patterns are checked against both text messages and media captions

• Invalid regex patterns are ignored with a warning in the gateway logs rather than crashing the bot

• If you want a pattern to match only at the start of a message, anchor it with ^

Private Chat Topics (Bot API 9.4)

Telegram Bot API 9.4 (February 2026) introduced Private Chat Topics — bots can create forum-style topic threads directly in 1-on-1 DM chats, no supergroup needed. This lets you run multiple isolated workspaces within your existing DM with Hermes.

Use case

If you work on several long-running projects, topics keep their context separate:

• Topic "Website" — work on your production web service

• Topic "Research" — literature review and paper exploration

• Topic "General" — miscellaneous tasks and quick questions

Each topic gets its own conversation session, history, and context — completely isolated from the others.

Configuration