Messaging Gateway Guide

Hermes Agent Telegram Bot Setup

Interact with Hermes Agent directly from Telegram on iOS, Android, macOS, and desktop. Follow this guide to create your bot token, configure an allowlist or pairing, and troubleshoot common silent bot issues. Using a Discord server instead? See Hermes Agent on Discord — there Hermes answers only when mentioned by default.

Fastest route: Create with QRIn the web dashboard or Hermes Desktop, open Messaging → Telegram and click Create with QR. Scan it in Telegram and Hermes creates the bot, detects your user ID, writes TELEGRAM_BOT_TOKEN and TELEGRAM_ALLOWED_USERS to your profile's .env, and restarts the gateway. The manual steps below do the same thing by hand.Checked against the official Telegram docs on September 26, 2026.

No Public Ingress in the Default Mode: Hermes uses long-polling by default to communicate with Telegram servers. You do not need open incoming ports, static public IPs, or SSL certificates unless you configure webhook mode.

Setup Workflow

5-Step Integration Process

Create Bot Token with @BotFather

Open Telegram, start a chat with the official @BotFather, and create your new bot:

Send /newbot to @BotFather.
Choose a friendly display name (e.g., "My Hermes Assistant").
Choose a unique username ending in 'bot' (e.g., "my_personal_hermes_bot").
Copy the HTTP API Token provided (format: 123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ).

# Keep your token private — never commit to public git repos!
$TELEGRAM_BOT_TOKEN="123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ"

Customize the Bot Profile (Optional)

Hermes registers its command menu automatically when the gateway starts. Use BotFather only for optional profile details:

Send /setdescription, /setabouttext, or /setuserpic to @BotFather.
Select your bot from the list.
No manual /setcommands step is needed.

# No manual command registration required.
# Start the Hermes gateway after configuration to register its menu.

Find Your Numeric User ID or Use Pairing

Hermes Agent can authorize Telegram users through numeric ID allowlists or its DM pairing flow. For an allowlist:

Open a chat with @userinfobot on Telegram (the method the official docs recommend).
Send any message. It will reply with your numeric ID (e.g., 987654321).
Record this number for your access control whitelist.

# Example allowlist entry in ~/.hermes/.env
$TELEGRAM_ALLOWED_USERS=987654321
$
# Or approve the one-time code returned to an unknown DM user:
$hermes pairing approve telegram ABC12DEF

Never use username strings (e.g., '@john_doe') in allowlists. Usernames can be changed or reassigned; numeric IDs are permanently bound to your account.

Configure Hermes Gateway

Run the interactive gateway configuration command or add the token and allowlist to ~/.hermes/.env:

# Run interactive gateway setup wizard:
$hermes gateway setup
$
# Or manually add to ~/.hermes/.env:
$TELEGRAM_BOT_TOKEN=123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ
$TELEGRAM_ALLOWED_USERS=987654321

Start & Verify the Gateway Service

Launch the gateway in the foreground for testing, or start its installed systemd service on a VPS:

# Test in foreground:
$hermes gateway run
$
# Or, after "hermes gateway install", start the background service:
$hermes gateway start
$
# On a VPS/headless server (system service):
$sudo hermes gateway install --system
$sudo hermes gateway start --system
$journalctl -u hermes-gateway -f

Enabling Hermes in Telegram Group Chats

Telegram Privacy Mode is enabled by default. Commands, direct replies, and messages Telegram identifies as addressed to the bot can still reach it. If you want Hermes to observe ordinary group messages, either promote the bot to group admin (admins always receive every message) or:

1. Disable Privacy Mode in @BotFather:

Send /setprivacy to @BotFather → select your bot → click Disable. Then remove the bot from the group and add it back — Telegram caches the privacy setting from when the bot joined.

2. Require a mention in config.yaml:

Set require_mention: true under telegram: in ~/.hermes/config.yaml so ordinary group chatter does not trigger replies. User and group allowlists still apply.

Troubleshooting: Why Is My Bot Silent?

If you send a message to your Telegram bot and receive no response:

1. Telegram User Is Not Authorized:

Hermes denies users who are neither allowlisted nor paired. Double check TELEGRAM_ALLOWED_USERS, or approve the pairing code with hermes pairing approve telegram <code>.

2. Multiple Bot Instances (Polling Conflict):

If another gateway is polling with the same bot token, Telegram rejects concurrent polling. Stop the duplicate gateway or give each profile its own bot token.

3. Works in DMs but Not in a Group:

Privacy mode is still in effect for that group. Remove and re-add the bot after changing /setprivacy, or make it an admin. Allowlists still apply inside groups.

4. The Gateway Isn't Running:

The bot only answers while hermes gateway runs. If it lives on a laptop, it goes quiet when the laptop sleeps — see Hermes hosting options. Check with hermes gateway status.

5. Check Gateway Logs:

For the VPS system service, run journalctl -u hermes-gateway -n 50 --no-pager to check for provider API key errors or network timeout issues.

Want 24/7 Uptime for Your Telegram Bot?

Run the gateway on a Linux VPS you manage, or use Hermes Cloud, where Telegram connects from the agent's dashboard. Serverless hosts that sleep between requests need Telegram's webhook mode (see the official Telegram docs).

VPS Deployment Guide →