| name | telegram-bridge |
| description | Bidirectional Telegram bot bridge for Ouroboros with configurable command modes, inline keyboard control panel, file/document delivery, and optional silent (edit-in-place) mirror. |
| version | 2.6.0 |
| type | extension |
| entry | plugin.py |
| runtime | python3 |
| permissions | ["net","read_settings","widget","route","supervised_task","subscribe_event","inject_chat"] |
| env_from_settings | ["TELEGRAM_BOT_TOKEN","OPENAI_API_KEY"] |
| subscribe_events | ["chat.outbound","chat.typing","chat.photo","chat.video","chat.document"] |
| when_to_use | User wants to communicate with Ouroboros through Telegram. |
| timeout_sec | 60 |
Telegram Bridge
Bidirectional Telegram bridge for Ouroboros. Polls Telegram for inbound
text/photos and mirrors host chat output back to Telegram.
Command Modes
Three configurable security modes control which slash commands are accepted
from Telegram (configure in Settings → Telegram Bridge):
| Mode | Allowed commands | Blocked |
|---|
| strict | None — all slash commands blocked | Everything with / |
| safe_commands | /status, /bg, /bg status | Mutating commands |
| full_access (default) | Raw owner commands including /panic, /restart, /review, /evolve, /bg | Unknown commands only |
Important: In full_access, this reviewed transport is a first-class owner
chat surface. Slash commands are forwarded as raw chat text through the Host
Service after the skill passes review, grants, enablement, token, rate-limit,
and chat/user binding checks. In full_access the bot's / command menu also
lists the owner-control commands (/evolve, /bg, /review, /restart,
/panic) so they are discoverable and tappable.
Control panel (/menu → Settings, full_access): pick the main model and the
budget via inline buttons. Budget offers +$50/＋$100/＋$500 increments and a
Custom amount button — tap it and type any $ amount in chat. Both model and
budget changes are injected as owner requests (the agent applies them through
the guarded settings flow); the skill never writes the core settings.json.
Subagent Activity
Ouroboros emits a progress event for every subagent state change (a parallel
swarm can fan out dozens). Instead of flooding Telegram with one bubble per
event, the bridge gives each subagent a single message that is edited in
place across its lifecycle (🔵 queued → 🟡 running → ✅ done · $cost). Each
card shows a status header plus the latest work note — the live commentary
you see in the Ouroboros web UI (e.g. "I will read lines 710–765 of llm.py…") —
so the bubble updates as the subagent works rather than posting a new line per
note. (An identical-text edit that Telegram rejects with "message is not
modified" is treated as a no-op, never as a reason to post a duplicate.) The
"Ouroboros is typing…" indicator covers the overall working signal, and your
real replies stay clean, separate messages.
Two settings (Settings → Telegram Bridge):
- Subagent cards (default on) — one updating message per subagent. Turn
off to hide subagent activity entirely.
- Mirror progress telemetry (default on) — streams the main agent's
progress notes (thinking, searches, cost lines). In silent mode it edits one
bubble in place; otherwise it posts one message per note. Set off for a
clean replies-only chat.
Push Notifications
Beyond mirroring chat replies, the bridge can send proactive notifications to
the pinned chat — useful for background/scheduled tasks that finish without you
watching. A separate notifier supervised task reads durable state files every
30s (read-only) and pushes structured one-liners. Both are off by default
(opt-in via Settings → Telegram Bridge):
- Notify on task completion — when a task writes its summary, push
✅ Task <id> done · <rounds>r · $<cost> (cost from task_results/<id>.json
when available; ⚠️ instead of ✅ for non-completed outcomes). Enabling the
toggle primes against the existing backlog, so you only get notified about
tasks that finish after you turn it on — no flood of old summaries.
- Notify on budget thresholds — push
⚠️ Budget: N% once when cumulative
spend crosses 80% / 90% / 100% of TOTAL_BUDGET. Each threshold fires once;
raising the budget (or a spend reset) re-arms the lower thresholds.
Notifications require a pinned TELEGRAM_CHAT_ID; with no pinned chat the
notifier stays idle. Dedupe/threshold state lives in the skill's own state dir
(notif_state.json), never in core settings.
Inline Keyboard
Send /menu in Telegram to get an inline button panel with available
commands (adapts to the current command mode). Button presses use non-slash
callback identifiers internally, then map to the same allowed command text as
ordinary Telegram messages.
Silent Mode
When enabled (Settings → Telegram Bridge → Silent mode, or the inline
🔕 Silent Mode toggle inside /menu → ⚙️ Settings), successive outbound
messages within a single conversation turn are edited in place via
editMessageText instead of posting new bubbles. Each new inbound user
message (or sent photo/video) resets the silent chain so the next reply
starts a fresh bubble. Default: off.
File Delivery
When Ouroboros delivers a finished file (report, .md/.csv/.html, PDF,
archive, code) via its send_file tool, the host publishes a chat.document
event and this bridge forwards it to the pinned chat with Telegram's
sendDocument (any file type, up to Telegram's bot limit). This is separate
from photo/video mirroring (chat.photo/chat.video), which stay inline.
Long text replies are chunked automatically: a message over Telegram's
4096-character limit is split on line/space boundaries and sent as several
messages instead of being silently dropped.
Inbound files (documents/video/audio you send TO the bot) are not ingested
yet — the bridge replies that only text, voice, and photos are supported rather
than silently ignoring the message. Full inbound file ingestion is a planned
host-side follow-up.
Setup
- Set
TELEGRAM_BOT_TOKEN in Settings → Secrets
- Grant the token to this skill
- Configure command mode, mirror mode, and chat ID in Settings → Telegram Bridge
- Toggle the skill on
TELEGRAM_BOT_TOKEN is a protected secret and requires an explicit owner
grant before the skill can run. Chat routing settings such as TELEGRAM_CHAT_ID
are owned by this skill's settings panel rather than by core settings. Use
full_access only for a bot/chat you trust as an owner channel.
