Analytics & Reporting Engine
Relevant source files
The following files were used as context for generating this wiki page:
The Analytics & Reporting Engine tracks member growth, engagement metrics, and chat activity to provide actionable insights for Telegram channel and group managers. It generates visual charts and trend analysis to monitor performance across multiple channels from a centralized dashboard.
Sources: README.md:143-146, README.md:179-183
Member & Engagement Tracking
The engine monitors member activities including joins, leaves, and overall growth. It tracks engagement metrics to identify active users and audience segments, supporting targeted broadcasting and moderation strategies.
Tracking Capabilities
- Member Growth: Visualizes increases or decreases in member counts over time.
- Activity Monitoring: Records user interactions to distinguish between active and new members.
- Trend Analysis: Provides daily breakdowns of chat behavior.
- Exporting: Supports CSV export of member categories and activity data.
Sources: README.md:112-115, README.md:144-145
Data Architecture for Metrics
The system utilizes a structured data approach to store and retrieve analytics. While the minimal bot implementation uses in-memory deque objects for recent message tracking, the full management suite supports SQL/JSON exports and automated backups.
The diagram shows how user activity is filtered, stored in the database, and then processed into visual charts or exportable reports.
Sources: README.md:179-183, bot.py:32-33
Key Data Components
| Component | Description | Source File |
|---|---|---|
| Member Activity | Tracks joins, leaves, and growth trends. | README.md:115 |
| Engagement Charts | Visual representations of daily breakdowns. | README.md:179-180 |
| Audit Logs | Tracks admin actions and permission changes. | README.md:175 |
| Usage Statistics | Records custom bot command performance. | README.md:129 |
Bot Command Statistics
The Analytics Engine records the performance and usage of custom bot commands. This data helps administrators understand which features are most utilized and identify potential issues in command execution.
Logic Flow for Message Processing
The sequence diagram illustrates how incoming messages are handled, either being stored for summarization or processed as commands, which are then logged for statistics.
Sources: bot.py:94-118
Configuration and Environment
Analytics behavior is influenced by environment variables that define data retention limits and logging verbosity.
| Variable | Description | Default |
|---|---|---|
MAX_STORED_MESSAGES | Limits the number of recent messages retained for analysis. | 100 |
LOG_LEVEL | Sets the granularity of system logs (e.g., INFO, DEBUG). | INFO |
POLL_TIMEOUT | Defines the duration for the update polling cycle. | 30 |
Sources: bot.py:20-22, README.md:46-52
Smart Insights & AI Reporting
The engine integrates AI-powered summarization (Gemini and ChatGPT) to provide smart content insights. It extracts key information from channel history to generate Q&A responses and summary reports, reducing the need for manual message review.
Local Summarization Logic
When the AI API is not used, a local extractive summarizer cleans text by removing extra whitespace and splitting it into sentences. It then returns a maximum number of sentences defined by SUMMARY_SENTENCES.
def summarize_text(text: str) -> str:
cleaned = " ".join(text.split())
if not cleaned:
return "No text found to summarize."
sentences = [
sentence.strip()
for sentence in cleaned.replace("!", ".").replace("?", ".").split(".")
if sentence.strip()
]
if not sentences:
return cleaned[:1000]
summary = ". ".join(sentences[:SUMMARY_SENTENCES])
return f"{summary}."
Sources: bot.py:65-80, README.md:150-153
The Analytics & Reporting Engine serves as a centralized intelligence layer, transforming raw Telegram chat data into visual growth charts, engagement trends, and automated content summaries to assist in professional channel management.