Hermes agent telegram threads work by adding Telegram's thread ID to the session key, so each DM thread, DM topic or forum topic runs as its own Hermes session with its own transcript.
This is the operator build: the BotFather switch, the four config surfaces, the filters for groups, the multi-bot setup and the log lines that tell you what went wrong.
Every key below is copied from the official Hermes Telegram docs and the sessions reference. The running example is a two-person web studio with one bot DM and one client supergroup.
If you'd rather map the layout with my team before you edit config.yaml, get your Backlink Gameplan, or try Polar Rank free for 3 days.
Before You Start: A Working Bot
This guide assumes the bot already replies in a plain DM.
If it doesn't, the full BotFather and token walkthrough is in our Hermes Agent Telegram setup guide.
Come back once hermes gateway status shows the gateway running and a test message gets an answer.
How Hermes Builds A Session Key From A Thread
Without threads, a Telegram DM maps to one key, and everything you send lands in one history:
agent:main:telegram:dm:<chat_id>
Inside a DM topic the key gains the thread ID, which is what isolates it:
agent:main:telegram:dm:<chat_id>:<thread_id>
A supergroup forum topic gets a group key with the thread ID on the end:
agent:main:telegram:group:<chat_id>:<thread_id>
That group key is shared by everyone in the topic by default; the sessions page says thread_sessions_per_user: true splits it per person.
For the studio, that means the client group's Design topic is one shared conversation, which is what you want when two people brief the agent together.
Step 1: Flip Threaded Mode In The BotFather Mini App
DM topics depend on a bot setting called Threaded Mode.
Open Telegram, search for botfather, and tap Open on the result to launch the Mini App.
Go to My bots, choose the bot, then Bot Settings, then Threads Settings, and switch Threaded Mode on.
The old /mybots text menu doesn't expose this toggle, which is why so many people think it doesn't exist.
Leave the option that lets users create topics switched on too, because the /topic mode checks for it.
Miss this step and the gateway log prints The chat is not a forum on startup and no topics are created.
Step 2: Set The DM Thread Policy
With Threaded Mode on, Telegram attaches a thread ID to ordinary DM messages as well, and Hermes treats each thread as its own session.
That default is called per_thread. Some clients open a thread per question, so a busy DM can fan out into dozens of sessions.
If that's not what you want, collapse it:
platforms:
telegram:
extra:
dm_threads: shared # per_thread (default) | shared
Shared gives you one history and one turn at a time, while replies still go back to whichever thread the message came from.
Any value other than the two names logs a warning and falls back to per_thread.
In the studio, per_thread suits the owner, who likes one thread per client question, while shared suits the designer, who prefers a single running chat on her own bot.
The v0.23.2 release lists this as opt-in shared Telegram DM threads, so update first if the key does nothing.
🔥 Want topic lanes that are already wired to skills? Inside the AI Profit Boardroom members install a ready-built Agent OS, watch step-by-step video trainings on every Hermes gateway, and bring their config to four live coaching calls a week with 3,400+ members. → Join the AI Profit Boardroom
Step 3: Declare Permanent DM Topics
For lanes you use every day, let Hermes create the topics from config. The studio wants three:
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
Only name is required. icon_color and icon_custom_emoji_id style the icon, and skill auto-loads a skill whenever a fresh session starts in that topic.
Never type thread_id here. On startup Hermes calls createForumTopic for each entry without one and writes the ID back into config.yaml.
Restarts, reconnects and adapter rebuilds reuse that saved ID, so you won't get duplicate topics after a network blip.
Every topic with an ID also goes into channel_directory.json, which lets send_message target it by name.
To turn the root DM into a lobby for users who have topics, add ignore_root_dm: true next to dm_topics; /start, /help and /status keep working there.
Step 4: Or Let Users Spawn Topics With /topic
The second DM model needs no YAML at all. The user sends /topic in the root DM.
Hermes calls getMe to confirm has_topics_enabled and allows_users_to_create_topics; if either is false it sends a screenshot of the BotFather settings page and stops.
Once active, the root DM is a lobby. Tapping All Messages and sending any text makes Telegram create a topic, and Hermes answers inside it as a new session.
/topic # root: enable, or list unlinked sessions
/topic # inside a topic: show its binding
/topic <session-id> # inside a topic: restore an old session
/topic off # root: disable and clear bindings
/new # inside a topic: reset that topic only
Bindings live in two SQLite tables in state.db, telegram_dm_topic_mode and telegram_dm_topic_bindings, keyed by profile name.
The migration runs on the first /topic call, never at gateway start, so a profile that never uses it keeps an untouched database.
Only users on the allowlist can run /topic; anyone else gets a refusal.
Restoring has two limits: the session must belong to the same Telegram user, and it can't already be bound to another topic.
A /bg prompt started inside a topic reports back to that same topic, and background sessions never trigger a rename.
Step 5: Tune The Lobby, Renames And Root Messages
Three keys change how /topic mode feels. All three sit under gateway.platforms.telegram.extra in the docs examples.
gateway:
platforms:
telegram:
extra:
dm_topic_auto_transfer: true # default false
disable_topic_auto_rename: true # keep hand-picked names
By default, a root-DM message with no thread ID is answered in the user's most recently active topic.
dm_topic_auto_transfer instead opens a new topic called Hermes Chat until the auto-title renames it; it shipped in v0.23.0.
Topics are renamed to the session title after the first exchange unless disable_topic_auto_rename is on. Topics declared in dm_topics are never renamed.
If a topic is deleted, Hermes retries once, then posts to the root chat and drops that binding.
Step 6: Forum Topics In A Supergroup
The studio's client group has Topics mode on, so per-topic sessions already work without config.
To bind skills per topic, map the thread IDs yourself, because the admin created those topics in the Telegram app:
platforms:
telegram:
extra:
group_topics:
- chat_id: -1001234567890
topics:
- name: Engineering
thread_id: 5
skill: software-development
- name: Research
thread_id: 12
skill: arxiv
- name: General
thread_id: 1
Find a thread ID by opening the topic in Telegram Web or Desktop: in https://t.me/c/1234567890/5 the last number is the ID.
The group's chat_id is that group number with -100 in front.
Unmapped topics fall through quietly, with session isolation and no skill.
Step 7: Fence The Bot In With Topic Filters
Group filters exist as telegram.* keys in config.yaml and as env variables, and they run in a fixed order. The env form is the easiest to show:
# ~/.hermes/.env (each one equals the matching telegram.* key in config.yaml)
TELEGRAM_ALLOWED_TOPICS=1,5
TELEGRAM_IGNORED_THREADS=31,42
TELEGRAM_FREE_RESPONSE_TOPICS=-1001234567890:5
allowed_topics is the whitelist and runs first. Messages from other topics are dropped, and the first drop per chat and topic is logged at INFO.
The General topic, and any group message without a message_thread_id, counts as topic 1. DMs are never filtered.
ignored_threads keeps Hermes silent in named topics before the mention and free-response checks run.
free_response_topics takes chat ID and thread ID pairs and lets that one topic skip require_mention, so the studio's Engineering topic answers without an @mention while the rest of the group stays mention-only.
Use the same IDs you found in Step 6, and check the gateway log after a restart to confirm the INFO drop lines look right.
📞 Rolling topics out for a whole team? Get your Backlink Gameplan and we'll walk through your groups, topics and filters with you, or try Polar Rank free for 3 days. Backlink Gameplan or try Polar Rank free for 3 days
Step 8: Run Several Profiles In One Group
A topic isolates a conversation; the profile's memory, skills, persona, model default and bot token are still shared by every topic.
When the studio wants a research agent and a deploy agent in the same group, that's two profiles.
The Hermes FAQ says two profiles can't share one bot token, so make a second bot in BotFather and run one gateway per profile:
hermes gateway start
hermes -p research gateway start
hermes -p research gateway status
The Telegram page recommends this group block for multi-bot rooms:
telegram:
require_mention: true
exclusive_bot_mentions: true
mention_patterns: []
A message that opens with one bot's handle then reaches that bot only. If two bots start quoting each other, set telegram.bots_require_mention: true.
The shared-bot alternative is a multiplexed gateway with gateway.profile_routes. Its matching tuple includes thread_id as well as chat_id, scored most specific first; the multi-profile gateway guide has the rules.
Step 9: Point Cron And Branches At Topics
Scheduled jobs can deliver into one topic. The cron docs accept a delivery target written as chat ID, colon, thread ID:
telegram:-100123:17585 # one forum topic
telegram:-100123:1 # the General topic
When /topic mode makes the root DM a lobby, set TELEGRAM_CRON_THREAD_ID in .env to a dedicated Cron topic, and replies to cron posts continue that topic's session.
/branch on Telegram opens the copy in a new sibling thread, per the slash command reference; add --here to switch the current chat instead.
/handoff telegram from the CLI opens a fresh topic for the handed-off session.
What Is Still An Open Issue
A model, toolset or working folder per topic isn't a config option yet.
Per-topic model overrides (#57664), DM-topic runtime defaults (#24179) and a bound working directory (#61136) are open requests.
Binding a topic to an external runtime such as Codex or Claude Code is issue #5394, also open, so it isn't built in yet.
The workaround that does work today: run /model inside a topic. A plain switch is session-only, so other topics keep the default; /model reset undoes it.
Gotchas And The Log Lines To Grep
The chat is not a forum: Threaded Mode is off for the bot.
Unread badges that don't match between All Messages and a topic are a Telegram read-state quirk the docs call expected behaviour.
A bot silent in one topic but fine in others is usually allowed_topics missing that ID, or the ID sitting in ignored_threads.
Two gateways fighting over updates means two profiles share a token; give each its own bot.
My Verdict On Telegram Threads In Hermes
Use /topic for personal parallel work, dm_topics for two or three permanent lanes with skills, and forum topics plus allowed_topics for teams.
Reach for a second profile only when a lane needs its own memory or credentials.
Members of the AI Profit Boardroom can bring their config.yaml to a live call and have the topic layout checked.
FAQ: Hermes Agent Telegram Threads
What makes a Telegram topic a separate Hermes session?
Hermes adds the topic's thread ID to the session key, so each DM topic or forum topic gets its own transcript and context window.
Why does the gateway log say the chat is not a forum?
Threaded Mode is off for the bot. Turn it on in the BotFather Mini App under Bot Settings, Threads Settings, then restart the gateway.
Should I set thread_id in dm_topics myself?
No. Hermes creates each topic with createForumTopic and writes the thread ID back to config.yaml. In group_topics you do set it by hand.
Which runs first, allowed_topics or ignored_threads?
allowed_topics runs first as a whitelist, then ignored_threads silences specific topics before the mention checks.
How do I run two Hermes agents in one Telegram group?
Create a second bot token, run a second profile with its own gateway, and keep require_mention and exclusive_bot_mentions on.
Can I give each topic its own model in config?
Not yet; it is an open GitHub request. Use /model inside the topic, which changes only that topic's session.
📺 Video notes + links to the tools 👉
🎥 Learn how I make these videos 👉
🆓 Get a FREE AI Course + Community + 1,000 AI Agents 👉
About Julian
I'm Julian Goldie, an SEO entrepreneur, author and founder of the AI Profit Boardroom, which has 3,400+ members.
I help business owners scale with AI agents, automation and SEO.
- I've built a 7-figure SEO and link building agency, Goldie Agency, with a team of 70+ SEO experts.
- I've grown a YouTube channel to 400,000+ subscribers.
- I wrote "Link Building Mastery".
- My Udemy courses have taught over 29,000 students.
→ Get my best AI training inside the AI Profit Boardroom
Switch on Threaded Mode, pick your DM model, map and filter your group topics, and if you want a hand, get your Backlink Gameplan or try Polar Rank free for 3 days with my team or get coached in the AI Profit Boardroom until hermes agent telegram threads run cleanly.











