839f798b74
Adds Discord-style mention gating for Telegram groups: - telegram.require_mention: gate group messages (default: false) - telegram.mention_patterns: regex wake-word triggers - telegram.free_response_chats: bypass gating for specific chats When require_mention is enabled, group messages are accepted only for: - slash commands - replies to the bot - @botusername mentions - regex wake-word pattern matches DMs remain unrestricted. @mention text is stripped before passing to the agent. Invalid regex patterns are ignored with a warning. Config bridges follow the existing Discord pattern (yaml → env vars). Cherry-picked and adapted from PR #1977 by mcleay. Fixed ChatType comparison to work without python-telegram-bot installed (uses string matching instead of enum, consistent with other entity_type checks). Co-authored-by: mcleay <mcleay@users.noreply.github.com>
289 lines
12 KiB
Markdown
289 lines
12 KiB
Markdown
---
|
|
sidebar_position: 1
|
|
title: "Telegram"
|
|
description: "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](https://python-telegram-bot.org/) 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](https://t.me/BotFather), Telegram's official bot management tool.
|
|
|
|
1. Open Telegram and search for **@BotFather**, or visit [t.me/BotFather](https://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](https://t.me/userinfobot) — it instantly replies with your user ID.
|
|
|
|
**Method 2:** Message [@get_id_bot](https://t.me/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)
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```bash
|
|
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
|
|
TELEGRAM_ALLOWED_USERS=123456789 # Comma-separated for multiple users
|
|
```
|
|
|
|
### Start the Gateway
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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](#step-3-privacy-mode-critical-for-groups))
|
|
- `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:
|
|
- slash commands
|
|
- replies to one of the bot's messages
|
|
- `@botusername` mentions
|
|
- matches for one of your configured regex wake words in `telegram.mention_patterns`
|
|
- 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
|
|
|
|
### Example group trigger configuration
|
|
|
|
Add this to `~/.hermes/config.yaml`:
|
|
|
|
```yaml
|
|
telegram:
|
|
require_mention: true
|
|
mention_patterns:
|
|
- "^\\s*chompy\\b"
|
|
```
|
|
|
|
This example allows all the usual direct triggers plus messages that begin with `chompy`, even if they do not use an `@mention`.
|
|
|
|
### 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
|
|
|
|
Add topics under `platforms.telegram.extra.dm_topics` in `~/.hermes/config.yaml`:
|
|
|
|
```yaml
|
|
platforms:
|
|
telegram:
|
|
extra:
|
|
dm_topics:
|
|
- chat_id: 123456789 # Your Telegram user ID
|
|
topics:
|
|
- name: General
|
|
icon_color: 7322096
|
|
- name: Website
|
|
icon_color: 9367192
|
|
- name: Research
|
|
icon_color: 16766590
|
|
skill: arxiv # Auto-load a skill in this topic
|
|
```
|
|
|
|
**Fields:**
|
|
|
|
| Field | Required | Description |
|
|
|-------|----------|-------------|
|
|
| `name` | Yes | Topic display name |
|
|
| `icon_color` | No | Telegram icon color code (integer) |
|
|
| `icon_custom_emoji_id` | No | Custom emoji ID for the topic icon |
|
|
| `skill` | No | Skill to auto-load on new sessions in this topic |
|
|
| `thread_id` | No | Auto-populated after topic creation — don't set manually |
|
|
|
|
### How it works
|
|
|
|
1. On gateway startup, Hermes calls `createForumTopic` for each topic that doesn't have a `thread_id` yet
|
|
2. The `thread_id` is saved back to `config.yaml` automatically — subsequent restarts skip the API call
|
|
3. Each topic maps to an isolated session key: `agent:main:telegram:dm:{chat_id}:{thread_id}`
|
|
4. Messages in each topic have their own conversation history, memory flush, and context window
|
|
|
|
### Skill binding
|
|
|
|
Topics with a `skill` field automatically load that skill when a new session starts in the topic. This works exactly like typing `/skill-name` at the start of a conversation — the skill content is injected into the first message, and subsequent messages see it in the conversation history.
|
|
|
|
For example, a topic with `skill: arxiv` will have the arxiv skill pre-loaded whenever its session resets (due to idle timeout, daily reset, or manual `/reset`).
|
|
|
|
:::tip
|
|
Topics created outside of the config (e.g., by manually calling the Telegram API) are discovered automatically when a `forum_topic_created` service message arrives. You can also add topics to the config while the gateway is running — they'll be picked up on the next cache miss.
|
|
:::
|
|
|
|
## Recent Bot API Features
|
|
|
|
- **Bot API 9.4 (Feb 2026):** Private Chat Topics — bots can create forum topics in 1-on-1 DM chats via `createForumTopic`. See [Private Chat Topics](#private-chat-topics-bot-api-94) above.
|
|
- **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](/user-guide/security). You can also use [DM pairing](/user-guide/messaging#dm-pairing-alternative-to-allowlists) for a more dynamic approach to user authorization.
|