NousResearchhermes-telegram-business
Part of Hermes Labs Plugins: built by Nous Research, not supported. Formerly in hermes-official-plugins and before that
NousResearch/hermes-telegram-business(archived); this directory carries its full history.
Observe-with-approval Telegram Business Mode (secretary bot) for Hermes Agent.
Connect your Telegram Business account to your Hermes bot and it becomes your secretary: every incoming customer message gets an LLM-drafted reply delivered to your DM with inline buttons — nothing reaches the customer until you tap Send.
Customer → your Business account (via Business Mode)
↓ debounce 8s, draft once
Bot → your DM
💬 Carol wrote:
> Hey, are you free Friday afternoon?
📝 Suggested reply:
Friday afternoon works — anywhere between 2 and 5pm?
[✓ Send] [✎ Edit] [✕ Discard]
↓
Send → delivered to the customer via your Business connection
Edit → your next DM text becomes the outgoing message
Discard → dropped, the customer sees nothing
Safety properties
- No auto-send exists. Every reply requires an owner button tap, even when
can_replyis granted. - Owner-only buttons. Callbacks are authorized against the connection's
owner_user_id; anyone else gets⛔. - Drafts expire after 24h (configurable). Stale buttons no-op.
- Without
can_reply, the Send button is hidden — you're told to copy/paste manually instead of getting a button that silently fails. - Typing bursts coalesce — new messages within the debounce window supersede the prior draft, one draft per coherent thought.
Requirements
- Hermes Agent with plugin Telegram-handler support (
ctx.register_telegram_handler, hermes-agent PR #59159 / v0.18+) - A Telegram Business subscription on your personal account
- Your Hermes Telegram bot with Business Mode toggled on in @BotFather
- python-telegram-bot ≥ 21.1 (already installed with the Hermes Telegram platform)
Install
hermes plugins install hermes-telegram-business
Restart the gateway (hermes gateway restart). Then:
- @BotFather → your bot → Business Mode → enable.
- Telegram → Settings → Business → Chatbots → add your bot → pick which chats it can see, and whether it can reply on your behalf (needed for the Send button).
- Message your bot
/bizto confirm the connection is live.
Owner controls
| Command | Effect |
|---|---|
| /biz | status dashboard |
| /biz pause / /biz resume | global drafting kill switch |
| /biz off <chat_id> / /biz on <chat_id> | per-customer-chat mute |
Configuration
Optional block in ~/.hermes/config.yaml:
plugins:
entries:
telegram-business:
debounce_seconds: 8 # coalesce typing bursts
draft_ttl_hours: 24 # stale-draft expiry
max_customer_text_chars: 4000
owner_persona: >
You are drafting replies for a freelance photographer.
Friendly, brief, always suggest a concrete next step.
Drafting uses your active Hermes model through the host-owned plugin LLM surface (ctx.llm) — no separate API key.
State
Plugin-owned SQLite at ~/.hermes/telegram-business/state.db (two tables: connections + drafts). Hermes' core state is never touched. Delete the file to reset.
v1 limits
- Text only — customer media (photos, voice, documents) is skipped; captions do trigger drafts.
- No conversation history — each customer message is drafted in isolation. The Edit button absorbs the gap.
- No persona learning from edits — your overrides go to the customer but don't train future drafts.
Tests
python3 -m pytest
37 tests covering connection lifecycle, draft supersession, debounce coalescing, all three button paths, edit capture, owner-scoped callback authorization, and /biz subcommands. No network, no live Telegram.
Credits
Based on the design and implementation from hermes-agent#30055, replatformed as a standalone plugin. Related earlier community proposals: #26654 by @evgyur (earliest submission), #35342 by @MilekhinAV, #46728 by @kxnkxv.
License
MIT
README from the reviewed commit 0480b2e; it updates when the author re-pins.
