Introduction to Telegram History Bot
Relevant source files
The following files were used as context for generating this wiki page:
The Telegram History Bot is a Cloudflare Worker application. It collects, stores, and analyzes Telegram chat history to provide user statistics and AI-generated summaries. Sources: README.md:3-5, AGENTS.md:3-5.
The bot operates within the Cloudflare ecosystem, utilizing Workers for logic, KV for short-term storage, D1 for persistent relational data, and Durable Objects for state management. It provides automated summaries via Workers AI or OpenAI and performs content analysis for profanity and criminal code violations. Sources: README.md:10-15, AGENTS.md:126-130.
System Architecture
The bot uses a serverless architecture based on Cloudflare Workers. It handles two primary types of entry points: webhooks from Telegram for real-time updates and scheduled cron triggers for background tasks. Sources: src/index.ts:38-42, src/index.ts:388-392.
Core Components
The following table summarizes the primary technical components of the system:
| Component | Technology | Purpose |
|---|---|---|
| Main Worker | Cloudflare Worker | Handles incoming webhooks, routes commands, and initiates analysis. |
| Message Storage | Cloudflare KV | Stores raw chat messages with a 7-day TTL. |
| Counters | Durable Objects | Manages per-user and per-chat activity metrics in real-time. |
| Summary Database | Cloudflare D1 | Archives violations history and historical chat summaries. |
| AI Processing | Workers AI / OpenAI | Generates text summaries and performs content analysis. |
Sources: README.md:10-15, AGENTS.md:126-132, src/index.ts:436-440.
System Data Flow
The following diagram illustrates how a message travels from a Telegram chat to the storage and analysis layers.
The system validates every webhook via a secret token before recording the message to KV storage and updating counters in Durable Objects. Sources: src/index.ts:187-200, src/index.ts:245-246.
Summary System
The bot implements an optimized summary system to handle high message volumes and long time periods efficiently. It supports two modes: /summary <days> for date ranges and /summary_last <n> for specific message counts. Sources: README.md:18-20, src/features/summary/summary.ts:803-818.
Hierarchical Processing
For large datasets, the bot uses a HierarchicalProcessor to stay within AI context limits. This involves a three-stage pipeline:
- Preprocessing: Messages are split into optimal chunks.
- Aggregation: The system generates per-user summaries for each chunk.
- Finalization: Aggregated user summaries are merged into a final report.
Sources: src/features/summary/optimization/hierarchical-processor.ts:28-32.
The hierarchical processor ensures that even sparse or dense data volumes do not exceed the SUMMARY_OPT_MAX_TOKENS_PER_REQUEST limit. Sources: src/features/summary/optimization/hierarchical-processor.ts:74-85, README.md:73-75.
Content Analysis and Statistics
The bot monitors chats for specific violations and tracks user engagement metrics.
Statistical Commands
Users interact with the bot using the following commands:
/top <n>: Shows top active users for the current day./profanity_top: Displays users with the highest profanity usage./criminal_stats: Provides statistics on criminal code violations./activity_week: Generates a weekly activity chart.
Sources: README.md:21-36.
Formatting and Safety
The system uses specialized utilities to format analysis results for Telegram's HTML parse mode. The html-utils.ts module manages severity indicators (Green, Yellow, Red) and escapes special characters to prevent message corruption. Sources: src/core/html-utils.ts:20-30, src/core/html-utils.ts:47-53.
Configuration
Environment variables define the bot's behavior and AI settings.
| Variable | Default | Description |
|---|---|---|
SUMMARY_OPT_ENABLED | true | Enables the optimized hierarchical summary system. |
SUMMARY_PROVIDER | cloudflare | Selects between cloudflare or openai. |
SUMMARY_OPT_MAX_WORKERS | 5 | Defines parallel Durable Object workers for fetching. |
KV_BATCH_SIZE | 50 | Sets the concurrent request limit for KV operations. |
Sources: README.md:68-76, src/features/summary/summary.ts:167-175.
Conclusion
The Telegram History Bot provides a robust framework for chat monitoring and AI-driven insights. By combining Cloudflare's serverless infrastructure with hierarchical AI processing, the system maintains high performance while staying within API and context constraints. Sources: tests/performance-report.md:78-85.