hermes-agent/website/docs/user-guide/messaging/telegram.md

sidebar_position, title, description

sidebar_position	title	description
1	Telegram	Set up Hermes Agent as a Telegram bot

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

:::warning Keep your bot token secret. Anyone with this token can control your bot. If it leaks, revoke it immediately via /revoke in BotFather. :::

Step 2: Customize Your Bot (Optional)

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

Command	Purpose
/setdescription	The "What can this bot do?" text shown before a user starts chatting
/setabouttext	Short text on the bot's profile page
/setuserpic	Upload an avatar for your bot
/setcommands	Define the command menu (the / button in chat)
/setprivacy	Control whether the bot sees all group messages (see Step 3)

:::tip For /setcommands, a useful starting set:

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

:::warning You must remove and re-add the bot to any group after changing the privacy setting. Telegram caches the privacy state when a bot joins a group, and it will not update until the bot is removed and re-added. :::

:::tip An alternative to disabling privacy mode: promote the bot to group admin. Admin bots always receive all messages regardless of the privacy setting, and this avoids needing to toggle the global privacy mode. :::

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.

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"

:::tip Group chat IDs are negative numbers (e.g., -1001234567890). Your personal DM chat ID is the same as your user ID. :::

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)
• When privacy mode is on, @mention the bot (e.g., @my_hermes_bot what's the weather?) or reply to its messages to interact
• When privacy mode is off (or bot is admin), the bot sees all messages and can participate naturally
• TELEGRAM_ALLOWED_USERS still applies — only authorized users can trigger the bot, even in groups

Recent Bot API Features (2024–2025)

• Privacy policy: Telegram now requires bots to have a privacy policy. Set one via BotFather with /setprivacy_policy, or Telegram may auto-generate a placeholder. This is particularly important if your bot is public-facing.
• Message streaming: Bot API 9.x added support for streaming long responses, which can improve perceived latency for lengthy agent replies.

Troubleshooting

Problem	Solution
Bot not responding at all	Verify TELEGRAM_BOT_TOKEN is correct. Check hermes gateway logs for errors.
Bot responds with "unauthorized"	Your user ID is not in TELEGRAM_ALLOWED_USERS. Double-check with @userinfobot.
Bot ignores group messages	Privacy mode is likely on. Disable it (Step 3) or make the bot a group admin. Remember to remove and re-add the bot after changing privacy.
Voice messages not transcribed	Verify STT is available: install faster-whisper for local transcription, or set GROQ_API_KEY / VOICE_TOOLS_OPENAI_KEY in ~/.hermes/.env.
Voice replies are files, not bubbles	Install ffmpeg (needed for Edge TTS Opus conversion).
Bot token revoked/invalid	Generate a new token via /revoke then /newbot or /token in BotFather. Update your .env file.

Exec Approval

When the agent tries to run a potentially dangerous command, it asks you for approval in the chat:

⚠️ This command is potentially dangerous (recursive delete). Reply "yes" to approve.

Reply "yes"/"y" to approve or "no"/"n" to deny.

Security

:::warning Always set TELEGRAM_ALLOWED_USERS to restrict who can interact with your bot. Without it, the gateway denies all users by default as a safety measure. :::

Never share your bot token publicly. If compromised, revoke it immediately via BotFather's /revoke command.

For more details, see the Security documentation. You can also use DM pairing for a more dynamic approach to user authorization.