Skip to content

JPeetz/agent-skills / skills/development/telegram-topics-pipeline

telegram-topics-pipeline

Verified

Use this skill when setting up Telegram forum topics to run multiple independent bot sessions or automated pipelines in one group with isolated context, per-topic skills, cron delivery, and no cross-contamination between workflows.

Telegram Topics Pipeline

Wire Telegram's forum topics into your agent infrastructure so each topic is its own isolated agent session with dedicated context, skills, and cron pipeline. No context bleed. No accidental cross-posting. One group, N independent workflows.

This is the single highest-impact operational change you can make to how your agent runs. A flat DM or group chat forces every topic into the same context window. Topics fix that.


How It Works

Telegram forum topics (supergroups with Topics mode) each carry a unique message_thread_id. Hermes (and OpenClaw) use the pair (chat_id, thread_id) as a session key:

agent:main:telegram:dm:{chat_id}:{thread_id}     # DM topics
agent:main:telegram:group:{chat_id}:{thread_id}   # Group forum topics

Messages in Topic A never appear in Topic B's session history. They are independent conversations with their own scrollback, memory, and active context.


Step 0: Enable Topics

You must enable Topics on the Telegram side. The bot cannot do this.

  1. Create a Telegram group (or use an existing one)
  2. Add your bot to the group
  3. Go to Group Settings → Edit → Enable Topics (Forum mode)
  4. Create topics with descriptive names and emoji icons

If the bot is in privacy mode, either:

  • Turn it off via BotFather (/setprivacy → Disable), or
  • Make the bot a group admin (topics count as messages; privacy-mode bots only see messages that @mention them or slash commands)

Step 1: DM Topics (Hermes)

Add dm_topics under platforms.telegram.extra in ~/.hermes/config.yaml:

platforms:
  telegram:
    extra:
      dm_topics:
        - chat_id: 123456789          # Your Telegram user ID (integer)
          topics:
            - name: General
              icon_color: 7322096
            - name: Website
              icon_color: 9367192
            - name: Research
              icon_color: 16766590
              skill: arxiv             # Auto-loads arxiv skill in this topic
            - name: Engineering
              skill: software-development
            - name: Social Pipeline
              icon_color: 16752821
              skill: social-media       # Every session in this topic loads social-media

Field reference:

FieldRequiredDescription
nameYesTopic display name
icon_colorNoTelegram icon color code (integer)
icon_custom_emoji_idNoCustom emoji ID
skillNoSkill to auto-load on every new session in this topic
thread_idNoAuto-populated by Hermes after creation — don't set manually

On first gateway restart, Hermes calls createForumTopic for each entry without a thread_id and saves the ID back to config.yaml automatically.

Set ignore_root_dm: true to turn the root DM into a silent lobby — normal messages are ignored while slash commands (/start, /help, /status) still work:

platforms:
  telegram:
    extra:
      ignore_root_dm: true
      dm_topics:
        - chat_id: 123456789
          topics:
            - name: General
            - name: Research
              skill: arxiv

Step 2: Group Forum Topic Skill Binding (Hermes)

For supergroups where topics are created manually in the Telegram UI, use group_topics:

platforms:
  telegram:
    extra:
      group_topics:
        - chat_id: -1001234567890      # Group ID (prefixed with -100)
          topics:
            - thread_id: 5             # From URL: t.me/c/1234567890/5
              skill: marketing
            - thread_id: 8
              skill: software-development
            - thread_id: 12
              skill: research

To find a topic's thread_id: open the topic in Telegram Web or Desktop and look at the URL — https://t.me/c/1234567890/5 — the last number (5) is the thread_id. The group's chat_id is the group ID prefixed with -100.


Step 3: Cron Delivery to Topics

Route scheduled task output to a specific topic instead of the default chat:

cron:
  social-pipeline:
    schedule: "30 8 * * *"
    goal: "Generate and post today's BetterLife social content"
    target: "telegram:-1001234567890:31"   # telegram:<chat_id>:<thread_id>

The target format is: telegram:<chat_id>:<thread_id>

On Hermes, you can also use target: origin to send back to wherever the cron was registered from.


Step 4: User-Driven Multi-Session Mode (/topic)

For end-users who want to create topics on the fly without touching config:

  1. The user sends /topic in the bot DM
  2. Hermes verifies the bot has can_create_topics and threads_enabled flags (you must toggle these in BotFather first)
  3. User creates topics from the Telegram UI (+ button in the topic bar)
  4. Each topic gets its own isolated session
  5. The user can rename topics — Hermes auto-renames to match the session title

Commands:

CommandContextEffect
/topicRoot DMEnable multi-session mode
/topic offRoot DMDisable and clear all topic bindings
/topic helpAnyShow usage
/topic <session-id>Inside a topicRestore a previous session
/newInside a topicReset that topic's session

Pipeline Architecture Patterns

Pattern A: Separate Pipeline Per Topic

One group, three topics, three independent automated pipelines:

Group: "Agent HQ"
├── 📰 Social (topic 31)
│   └── Cron: 08:30 daily → generate + review + post social content
│       Skill: social-media, recurring-content-anti-repetition
├── 🔬 Research (topic 32)
│   └── Cron: 06:00 daily → web research digest → deliver to topic
│       Skill: arxiv, web-search
└── 🛠️ Engineering (topic 33)
    └── Cron: hourly → check PRs, run tests, report status
        Skill: software-development, github

Each pipeline runs autonomously. Results land in their own topic. You browse them when convenient.

Pattern B: Topic as Session Boundaries

DM
├── General (casual chat, quick questions)
├── Project Alpha (deep context, long research threads)
├── Client Reports (weekly deliverable production)
└── Agent Maintenance (skill updates, config changes)

Switch between topics freely. Each one picks up exactly where you left off.

Pattern C: Multi-Profile Routing

Each Hermes profile can connect its own bot. Map one bot per function:

BotTopicsPurpose
@fluffy_botGeneral, Social, EngineeringDaily ops
@research_botResearch, Deep-DivesHeavy research, no distractions
@monitor_botSystem Health, AlertsSilent monitoring, cron deliveries only

Configure under telegram.accounts or run separate gateway instances per profile.


Common Pitfalls

Bots don't see topic messages. — Privacy mode blocks them. Fix: disable privacy in BotFather OR make the bot a group admin.

Telegram "409 Conflict" errors. — Stale polling session from another process. Find and kill the duplicate: grep -rl <bot_token> ~/.hermes ~/.openclaw ~/.config.

Topic not appearing after config change. — Hermes only calls createForumTopic for entries without a saved thread_id. Delete the thread_id from config.yaml for that topic to force recreation.

Session bleeding between topics. — Verify each topic has a unique thread_id. Duplicate thread_ids share the same session key.

Cron output goes to the wrong topic. — Double-check the target format: telegram:<chat_id>:<thread_id> with no extra spaces.


Verification

After setup, verify isolation:

  1. Send a message in Topic A → reply
  2. Switch to Topic B → send unrelated message → reply (should show no knowledge of Topic A)
  3. Send /new in Topic A → verify Topic B's session is unaffected
  4. Check cron deliveries arrive in the correct topic
  5. For skill binding: send a message in a topic with skill: arxiv → the agent should have arxiv pre-loaded

References

writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall