Telegram Bot Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Telegram Bot Integration in the BrightPath AI Operations System serves as a delivery mechanism for high-level manager briefings. While the core agent pipeline processes inbound sales and customer service messages, the Telegram interface is specifically designed to provide a concise, "scannable" summary of system activity, alerts, and items requiring human intervention directly to the business owner's mobile device.
Sources: README.md:22-24, agents/manager_briefing_agent.md:4-9
System Architecture
The integration operates as a lightweight wrapper around the core orchestrator.py logic. Instead of running the full terminal-based interactive loop, the system provides a specialized "silent" entry point that processes messages and returns a structured dictionary optimized for Telegram's messaging format.
The Silent Orchestrator
The primary interface for the Telegram bot is the process_message_for_telegram() function. Unlike the standard process_message() function which uses rich for console formatting, this version executes the three-agent pipeline (Triage -> Specialist -> Briefing) and returns a clean data object.
This diagram shows the flow of a message from a third party through the bot integration to the final manager summary.
Sources: orchestrator.py:275-312, README.md:154-162
Data Flow and Payload Structure
The Manager Briefing Agent is specifically instructed to produce a telegram_summary field within its JSON output. This summary is constrained to under 120 words and utilizes specific emoji triggers to indicate message priority and category.
Summary Response Object
The structured result returned to the Telegram bot includes the following keys:
| Key | Type | Description |
|---|---|---|
summary | string | The punchy, emoji-prefixed message content. |
action | string/null | Specific human action required (if any). |
value | string/null | Revenue opportunity details flagged with 💰. |
risk | string/null | Potential concerns or escalations flagged with 🚨. |
Sources: orchestrator.py:307-312, agents/manager_briefing_agent.md:21-34
Emoji Indicators
The Briefing Agent uses a standardized set of emojis to ensure the manager can categorize the notification at a glance:
- 💰 Sales / Revenue: High-value opportunities or new leads.
- ✅ Resolved: Successfully handled customer service queries.
- ⚠️ Attention: General items needing manual review.
- 🚨 Escalation: Hostile sentiment or priority complaints.
- 📋 Admin: Internal reporting or general updates.
Sources: agents/manager_briefing_agent.md:14-18, agents/manager_briefing_agent.md:36-38
Technical Implementation
Core Processing Logic
The process_message_for_telegram function in orchestrator.py handles the following internal steps:
- Memory Retrieval: Loads historical context from
.mdfiles to inform the agents. - Triage Execution: Classifies the message and identifies the next specialist.
- Specialist Action: Sales or Customer Service agent generates a draft and logs internal actions.
- Briefing Generation: The
Manager Briefing Agentsynthesizes the previous steps into the final Telegram payload. - Side Effects: Updates the SQLite database (
events,tasks,crm_log) so the Telegram activity is synchronized with the Web UI.
Sources: orchestrator.py:275-305, app.py:116-126
Sequence of Operations
This sequence illustrates how the Telegram integration interacts with the external Anthropic API and the internal database.
Sources: orchestrator.py:280-305, README.md:154-162
Configuration and Dependencies
To enable the integration, the following environment variables and libraries are required:
- Library:
python-telegram-bot>=22.0(specified inrequirements.txt). - Token: A bot token generated via Telegram's @BotFather.
- Agent Policy: The system prompt for the Manager Briefing Agent must be set to "Telegram-ready" mode to ensure valid JSON output without preamble.
Sources: requirements.txt:4, README.md:154-158, agents/manager_briefing_agent.md:21
The Telegram Bot Integration provides the BrightPath system with a high-priority notification channel. By leveraging the specialized process_message_for_telegram function and the emoji-coded outputs of the Briefing Agent, the system ensures that managers remain informed of critical business events and revenue opportunities without needing to monitor the full terminal or web dashboard.