Telegram Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Telegram Integration serves as the primary interactive channel for Cogmo, enabling personal direct message (DM) communication between a user and the agent. It is implemented as a pluggable channel adapter that adheres to the system's AdapterModule contract, utilizing the grammY library for communication with the Telegram Bot API.
This integration manages the entire lifecycle of a Telegram-based conversation, from initial user authentication and session resolution to the rendering of complex agent outputs. It acts as a specialized I/O layer that translates platform-specific events (text messages, photos, voice notes) into canonical system formats and back again, ensuring the agent remains platform-agnostic.
Sources: design/transport/telegram.md:1-12, design/transport/overview.md:118-124, design/decisions.md:10-15
Architecture and Components
The Telegram integration is built around a layered architecture where the Telegram Adapter interacts exclusively with the Transport layer. This decoupling ensures that the core agent logic never interacts with Telegram-specific APIs directly.
Component Overview
| Component | Responsibility |
|---|---|
| TelegramAdapter Class | Manages the Bot instance, active streams, and delivery of messages. |
| TelegramStreamHandle | Handles real-time token delivery by progressively editing Telegram messages. |
| Command Handlers | Pure functions that process user commands like /profile or /resume. |
| Markdown Renderer | A pipeline that converts standard Markdown into Telegram's supported HTML subset. |
| Boundary Logic | Manages "boundary holds" to prompt users when resuming old conversations. |
Sources: src/transport/adapters/telegram/index.ts:107-113, design/transport/adapters.md:158-164, src/transport/adapters/telegram/commands.ts:1-6
Data Flow: Inbound Message
The following diagram illustrates how a message sent by a user on Telegram reaches the agent.
The adapter intercepts control commands (e.g., /new, /end) before they reach the agent, mapping them to Transport methods for immediate execution.
Sources: design/transport/telegram.md:16-25, src/transport/adapters/telegram/index.ts:634-648
Session and Conversation Management
The integration maintains one long-lived session per Telegram DM. Sessions are created upon the first message and typically remain active until explicitly closed or replaced by commands.
Key Commands
| Command | Action | Source |
|---|---|---|
/new [profile] | Closes current session and starts a fresh conversation. | design/transport/telegram.md:27 |
/resume <alias> | Switches the DM to an existing conversation by its alias. | src/transport/adapters/telegram/commands.ts:121-126 |
/sessions | Lists available conversations, rendered as an inline keyboard or text list. | src/transport/adapters/telegram/commands.ts:99-105 |
/name <alias> | Sets or clears a human-readable alias for the current conversation. | src/transport/adapters/telegram/commands.ts:223-228 |
/end | Closes the current session; the next message will start a new one. | src/transport/adapters/telegram/commands.ts:250-255 |
Sources: design/transport/telegram.md:27-39, src/transport/adapters/telegram/commands.ts:99-255
Session Resolution Logic
Content Rendering and Delivery
Telegram has specific limitations on message length (4096 characters) and supported formatting. The integration uses a specialized rendering pipeline to ensure agent output is displayed correctly.
Rendering Pipeline
The system converts canonical Markdown (generated by the LLM) into a Telegram-compatible HTML subset through the following stages:
- Preprocessing: Fixes known parser breakages, such as inserting spaces between emojis and bold markers (
**). - GFM Parsing: Uses the
markedlibrary to convert GitHub Flavored Markdown to HTML. - Telegramization: A regex-based transform that:
- Wraps tables in
<pre>tags. - Converts headings to bold text with newlines.
- Strips unsupported HTML tags while keeping
<b>,<i>,<code>,<a>, etc. - Collapses excessive newlines.
- Wraps tables in
Sources: src/transport/adapters/telegram/render.ts:1-124, design/transport/adapters.md:180-192
Streaming Edits
For real-time response feedback, the TelegramStreamHandle manages progressive message updates.
- Throttling: Edits are throttled to a default interval (500ms) to respect Telegram rate limits.
- Chunking: If a response exceeds the character target (default 4000), the handler split-drains the accumulated text into multiple messages.
- Code Block Rebalancing: If a split occurs inside a fenced code block, the handler automatically closes the block in the first message and re-opens it in the next message with the same language tag.
Sources: src/transport/adapters/telegram/index.ts:145-212, src/transport/adapters/telegram/index.ts:385-410
Multimedia and Voice Support
The Telegram adapter supports various media types, mapping them to the system's InboundContent blocks.
| Media Type | Handling Logic |
|---|---|
| Photos | Downloads the largest available version; uploads to the attachment store as image/jpeg. |
| Documents | Routes image/* MIME types to image blocks for LLM vision; others remain documents. |
| Voice | Downloads OGG/Opus clips; provides metadata like durationMs for transcription. |
| Generated Images | Delivered mid-stream via sendPhoto when a generate_image tool result is received. |
Sources: src/transport/adapters/telegram/index.ts:650-738, src/transport/adapters/telegram/index.ts:285-300
Interactive UI Components
The integration utilizes Telegram's inline keyboards for high-stakes user decisions, particularly in the "coding delegation" and "skills" pipelines.
- Plan Approval: When an agent proposes a coding plan, the adapter renders "Approve", "Revise", and "Cancel" buttons.
- Tool Gate: For sensitive operations (e.g.,
git push), the system posts a "Permission Requested" message with "Allow Once", "Allow for Task", and "Deny" options. - Skills Approval: New skill deployments prompt the user for "Approve" or "Deny" before becoming live.
Sources: src/transport/adapters/telegram/index.ts:842-882, src/transport/adapters/telegram/commands.ts:470-520
Security and Identity
The integration operates in mapped identity mode. Users must be present in the user_identities table (the allowlist) to interact with the bot. Unauthorized users are rejected by the adapter before any conversation is created.
Sources: src/transport/adapters/telegram/index.ts:620-625, design/transport/overview.md:10-15
Conclusion
The Telegram Integration provides a robust, user-friendly interface for Cogmo while maintaining strict separation between platform concerns and agent logic. Through sophisticated rendering, streaming management, and interactive command handling, it delivers a seamless personal assistant experience directly within a standard messaging environment.