Bot Commands Reference
Relevant source files
The following files were used as context for generating this wiki page:
The Bot Commands Reference describes the interactive interface for the Telegram History Bot. This bot processes user messages to generate conversation summaries, calculate chat statistics, and analyze content for profanity or legal violations. Users interact with the bot using slash commands that trigger specific logic within the Cloudflare Workers environment.
Sources: README.md:1-15, src/index.ts:1-25, tests/integration/README.md:1-10
Command Execution Flow
When a user sends a command in a Telegram chat, the bot processes the update through a webhook. The system distinguishes between regular messages, which it records for history, and command messages, which it routes to specific feature modules like stats, summary, or violation handlers.
The diagram shows the routing logic from the initial Telegram update to the specific subsystem responsible for the command.
Sources: src/index.ts:182-225, tests/telegram-integration.test.ts:108-160, tests/integration/comprehensive-e2e.test.ts:180-210
Summary Commands
Summary commands generate text overviews of past chat messages using AI providers. The bot implements an optimized summary system that supports parallel processing and hierarchical chunking for large datasets.
| Command | Argument | Default | Description |
|---|---|---|---|
/summary | <days> | 1 | Summarizes the conversation for the last N days. |
/summary_last | <n> | 100 | Summarizes the last N messages (Maximum: 1000). |
Sources: README.md:21-23, tests/integration/README.md:13-14, tests/integration/comprehensive-e2e.test.ts:80-92
Summarization Logic
- The bot fetches messages from KV storage or Durable Objects based on the requested range.
- If the dataset is large, the Optimized Summary System splits messages into chunks for parallel processing.
- The system sends the processed text to an AI provider (Cloudflare AI or OpenAI).
- The bot returns the generated summary to the chat.
Sources: README.md:38-55, src/index.ts:13-16
Statistics and Activity Commands
Statistics commands provide insights into chat engagement and user behavior. These commands pull data from Durable Objects that track message counts and timestamps.
| Command | Argument | Default | Description |
|---|---|---|---|
/top | <n> | 5 | Lists the top N active users for the current day. |
/activity_week | None | N/A | Displays an activity chart for the current week. |
/activity_month | None | N/A | Displays an activity chart for the current month. |
/activity_users_week | None | N/A | Shows per-user activity distribution for the week. |
/activity_users_month | None | N/A | Shows per-user activity distribution for the month. |
Sources: README.md:24-34, tests/integration/README.md:15-18, tests/integration/comprehensive-e2e.test.ts:94-104
Content Analysis Commands
The bot features advanced analysis for profanity and potential legal (Criminal Code) violations. These systems use a combination of local pattern matching and AI-based contextual analysis.
Profanity Statistics
Profanity commands track the usage of restricted language within the chat over specific periods (today, week, or month).
/profanity_top [n] [period]– Top N users using profanity./profanity_words [n] [period]– Most frequently used profanity words./my_profanity [period]– Individual profanity statistics for the requester./profanity_chart_week//profanity_chart_month– Visual trends of profanity usage.
Sources: README.md:25-30, tests/integration/comprehensive-e2e.test.ts:106-135
Criminal Code Analysis
Criminal code commands interact with the CriminalCodeAnalyzerDO to report on potential violations identified in chat history.
/criminal_stats [period]– General statistics of detected violations./my_criminal [period]– Personal violation history for the user./criminal_top [n] [period]– List of users with the highest violation counts.
Sources: README.md:31-33, tests/telegram-integration.test.ts:108-160, src/durable-objects/criminal-code-analyzer-do.ts:145-165
The sequence diagram illustrates how a criminal statistics request is delegated to the specialized Durable Object and underlying D1 database.
Sources: src/index.ts:151-175, src/durable-objects/criminal-code-analyzer-do.ts:405-445
Administrative and System Commands
These commands are restricted or used for system maintenance. Some require the user to be configured as an admin in the environment variables.
| Command | Access | Description |
|---|---|---|
/reset | Chat Admin | Resets all message and activity counters for the current chat. |
/profanity_reset | Chat Admin | Resets profanity-specific counters. |
/criminal_reset | Chat Admin | Resets criminal violation counters. |
/auto_notifications | Chat Admin | Manages automated daily/weekly summary notifications. |
/test_race_conditions | Bot Admin | Runs internal tests to verify data consistency under load. |
/help | All | Provides the full list of available commands. |
Sources: README.md:34-37, tests/integration/comprehensive-e2e.test.ts:65-78, tests/integration/comprehensive-e2e.test.ts:155-178
Summary
The Telegram History Bot provides a robust command set for chat management and analysis. Commands are categorized into summarization, statistical reporting, and content moderation (profanity and legal). Most commands support optional time periods and limits, allowing users to customize the data they receive. Administrative commands ensure that chat history and violation data can be managed or reset as needed.