Team Telegram Assistant

If you’ve ever wanted to chat with your Hermes Agent from your phone, send it a quick voice memo while walking the dog, or have it drop scheduled task results into a group chat, the Telegram integration is about to become your new best friend.

This guide walks you through setting up your own Telegram bot, customizing it to feel like a polished product, and using some seriously cool new features that make the experience way smoother.

Quick Setup (Dashboard and Desktop App)

The Messaging → Telegram page in the dashboard and the desktop app has a Create with QR button. Scan the code (or open the link) in Telegram; Hermes creates the bot for you, detects your Telegram user ID, writes TELEGRAM_BOT_TOKEN and TELEGRAM_ALLOWED_USERS into your profile’s .env, and restarts the gateway. If you prefer to create the bot yourself, follow the manual steps below.

Step 1: Create Your Bot (It’s Easier Than You Think)

First, you need a bot. Telegram’s official bot manager, @BotFather, handles all the paperwork.

Open Telegram and search for @BotFather (or visit t.me/BotFather)
Send /newbot
Pick a display name — anything you like, like “Hermes Agent”
Choose a username — this must be unique and end in bot, like my_hermes_bot
BotFather will reply with your API token — it looks like this:

123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

Important: Keep that token secret. Anyone with it can control your bot. If it ever leaks, revoke it immediately with /revoke in BotFather.

Step 2: Make Your Bot Look Professional (Optional)

Before you start chatting, a few quick BotFather commands can make your bot feel polished:

Command	What It Does
`/setdescription`	The “What can this bot do?” text users see before chatting
`/setabouttext`	Short text on the bot’s profile page
`/setuserpic`	Upload an avatar
`/setcommands`	Define the command menu (the `/` button in chat)
`/setprivacy`	Control group message visibility (more on this later)

For /setcommands, a good starting set is:

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

New: Online/Offline Status Indicator

Telegram bots don’t have a green “online” dot like user accounts. But Hermes can fake it nicely using the bot’s short description — the line under its name on the profile page.

Enable status_indicator in your config, and Hermes sets that line to Online when connected and Offline on a clean shutdown:

gateway:
  platforms:
    telegram:
      extra:
        status_indicator: true
        # Optional custom strings (defaults: "Online" / "Offline"):
        status_online: "🟢 Online"
        status_offline: "🔴 Offline"

A few notes:

The status is global — everyone sees it on the profile page, not as a live badge in chat.
Only a clean shutdown (like /stop) writes “Offline”. A crash leaves the last-known status.
It’s off by default since it changes the bot’s global profile.

New: Cold-Boot Pending Queue

By default, Hermes drops any messages that piled up in Telegram’s queue while the gateway was offline — a restart is treated as a clean slate. That’s fine for always-on servers, but not for a desktop you shut down overnight: messages sent during the outage vanish silently, with no log and no retry.

Set drop_pending_on_cold_boot: false to receive that backlog in order on startup instead:

platforms:
  telegram:
    extra:
      drop_pending_on_cold_boot: false

A few notes:

Default is true, so nothing changes unless you opt in.
Brief reconnects (network blips with the process still alive) always keep the queue.
After a crash, a preserved queue can redeliver a message the crashed instance had partly handled, so time-sensitive commands sent during a long outage will run on boot.

New: Repeated Inbound Updates

Telegram can occasionally deliver the same update twice, so Hermes suppresses repeated update_id values before message batching, command/media handling, observed group-history writes and plugin observers. The check is scoped to the receiving adapter and numeric bot ID — it does not deduplicate by text or message_id, and a genuine edit with a new update ID still gets processed.

This is bounded, in-memory protection, not an exactly-once guarantee:

The adapter remembers the most recent 4096 completed admissions, with no time expiry. Active updates stay claimed until dispatch and its scheduled PTB handler tasks finish, including nonblocking native plugins and registered error callbacks.
Reconnecting the same adapter keeps that history. Eviction, adapter replacement or a process restart can let an old update through again — nothing is written to a replay ledger on disk.
Failed or cancelled preparation releases its claim if nothing has been handed off. Once an update enters a batch/hold queue, gateway dispatch, an observer or a native plugin, a later error does not reopen it. Native plugins own their own partial effects, so entering their update or registered error callback counts as handoff. PTB’s own exception logging is not a handoff. Uncached static-sticker vision analysis is also a handoff: cancelling the await cannot undo an auxiliary model request already submitted. Caught preparation errors before any handoff remain retryable; an intentional refusal is terminal.
Releasing a claim only permits a later delivery; it does not request one from Telegram. Polling acknowledgement is independent of agent completion. This check does not retry failed replies or stop a downstream component from independently duplicating work.

If you suspect a late replay, compare both occurrences’ bot/profile, chat/topic, update_id, update kind, message_id and actual receive time. An edit can reuse message_id, and the message’s sent timestamp is not its receive time.

Hermes automatically registers its command menu when the gateway starts. The default cap is 60 commands — enough for all built-ins plus common skills, and reliable for Telegram’s payload limits.

If you have specific skill or plugin commands that must stay visible in the / picker, prioritize them:

platforms:
  telegram:
    extra:
      command_menu:
        max_commands: 60
        priority_mode: prepend  # prepend | append | replace
        priority:
          - my_plugin_command
          - songsee          # skill commands work too

prepend: your commands first, then Hermes defaults
append: Hermes defaults first, then yours
replace: use only your list for priority ordering

The key improvement: prioritized commands are guaranteed a slot before the cap is enforced. Previously, skills were trimmed alphabetically, so late-alphabet skills could never appear. Now they can.

New: Inline Command Picker (No Cap!)

The / menu is capped, but Telegram’s inline mode is not. Once enabled, type @yourbotname in any chat and search across every Hermes command and skill — live, per keystroke, paginated, nothing trimmed:

@yourbotname plan            → tap the /plan result to send it
@yourbotname plan migrate auth to OIDC   → sends /plan migrate auth to OIDC
@yourbotname pdf             → finds skills matching "pdf" by name or description

The first word filters the catalog; everything after it becomes the command’s argument. Tapping a result sends the command as a normal message from you.

One-time setup: Inline mode is off by default. Enable it in @BotFather with /setinline (pick your bot, set placeholder text like “Search commands and skills…”). Until then, the picker stays inert.

Security bonus: results are only served to users on your gateway allowlist. Unauthorized users get an empty list, so your skill catalog stays private.

New: Concurrent Update Handling

Updates from different chats are processed concurrently, so one slow turn (a long provider retry, a large download) no longer stalls every other chat. Updates from the same chat still run one after another, in arrival order.

The cross-chat pool defaults to 32. An invalid value logs a warning and falls back to the default:

platforms:
  telegram:
    extra:
      max_concurrent_updates: 32   # 1 restores fully sequential processing

New: Clarify Timeout

When the agent asks you a clarifying question, it waits for your reply. Configure how long via agent.clarify_timeout in ~/.hermes/config.yaml (default 3600 seconds). If you don’t respond in time, the agent unblocks with "outcome": "timed_out" and adapts rather than hanging. Reply skip to skip a question.

Step 3: Privacy Mode

Privacy mode controls whether your bot sees all group messages or only ones that mention it or use commands. This is critical for group chats — check the full docs for details on configuring it correctly.

New: Threaded Mode for Topics

Before adding topics to your config, the bot owner must enable Threaded Mode for the bot in @BotFather:

Open the BotFather Mini App (search botfather in Telegram, then tap Open on the search result — the classic /mybots text menu does not expose this setting)
Go to My bots → your bot → Bot Settings → Threads Settings
Turn on Threaded Mode

There is no “Topics” toggle in the DM chat itself — a bot DM is not a group, so the group-forum toggle described in some older guides does not apply here. Without Threaded Mode, Hermes will log The chat is not a forum on startup and skip topic creation.

New: Messages Sent in the Root DM

Some Telegram clients deliver a message typed in the root DM (General / All Messages) without a message_thread_id. By default Hermes treats such a message as a continuation and answers it in your most recently active topic (lobby recovery).

To get a fresh session for every root-DM message instead, turn on dm_topic_auto_transfer:

gateway:
  platforms:
    telegram:
      extra:
        dm_topic_auto_transfer: true   # default: false

With it on, a plain message in the root DM makes Hermes create a new topic (named “Hermes Chat” until the auto-title renames it), start a new session there, and post the reply inside that topic. Slash commands typed in the root DM stay lobby commands and never create a topic. If creating the topic fails (for example Threaded Mode was switched off in BotFather), Hermes falls back to the default behaviour and answers in your most recently active topic. The key only matters while /topic mode is on. The top-level telegram.extra.dm_topic_auto_transfer key (shown in Desktop Settings) works too.

New: Bot-to-Bot Loop Guard

If you run multiple Hermes bots in one group with TELEGRAM_ALLOW_BOTS=all, two bots that answer each other’s quote-replies can loop forever. Setting telegram.bots_require_mention: true (env TELEGRAM_BOTS_REQUIRE_MENTION) closes that path: a message from another bot only triggers a response when it explicitly @mentions this bot, while human replies keep working unchanged. A bot-to-bot loop guard also meters every chat where bot-authored messages are admitted — once 20 bot messages land in one chat inside 5 minutes, further bot messages in that chat are dropped for 10 minutes and one warning is logged, while human messages are never counted or dropped. Settings live in config.yaml:

gateway:
  bot_loop_guard:
    enabled: true        # false turns the guard off
    max_events: 20       # bot messages per chat per window
    window_seconds: 300
    cooldown_seconds: 600

A legitimate high-volume bot posting more than 20 messages into one chat in 5 minutes trips the guard too; raise max_events for that gateway.

That’s it! You’re now ready to chat with your agent from anywhere, send voice memos that get auto-transcribed, and manage your team’s tasks right from Telegram.