Automated Notifications System
Relevant source files
The following files were used as context for generating this wiki page:
The Automated Notifications System manages the generation and delivery of scheduled reports regarding chat activity, profanity analysis, and criminal code violations. It provides a configurable framework for chat administrators to receive periodic summaries or instant alerts based on analyzed Telegram history data.
The system integrates with the project's core analysis features to transform stored statistics and violation records into human-readable messages using pre-defined templates. Administrators manage these settings via the Admin Dashboard or specific bot commands like /auto_notifications.
Sources: README.md:1-20, src/core/models/notification-settings.ts:1-10
Core Data Models
The system relies on structured interfaces to define how notifications behave for each chat. The primary configuration object is the ChatNotificationSettings interface.
Notification Categories
The system supports six distinct notification types and four delivery frequencies:
| Type | Description | Default Frequency |
|---|---|---|
criminal_reports | Reports regarding detected criminal code violations. | instant |
profanity_reports | Statistics on the use of profanity. | daily |
activity_summary | Summary of user messaging activity. | daily |
daily_summary | Comprehensive daily chat overview. | daily |
weekly_summary | Long-term weekly trend analysis. | weekly |
monthly_summary | Monthly performance and activity metrics. | monthly |
Sources: src/core/models/notification-settings.ts:9-30, src/core/models/notification-settings.ts:149-200
System Relationships
The following diagram illustrates the relationship between chat settings, scheduled tasks, and the delivery context.
The diagram shows how global chat settings contain specific configurations for each notification type, which the service then uses to create scheduled notification records.
Sources: src/core/models/notification-settings.ts:32-110
Notification Service Architecture
The system uses a layered architecture consisting of a repository for data persistence and a service for business logic.
NotificationService
The NotificationService acts as the primary API for managing notifications. It handles:
- Updating chat-specific settings and verifying permissions.
- Scheduling future notification tasks.
- Processing the queue of pending notifications.
- Calculating delivery times based on
NotificationTimeandquietHours.
Sources: examples/notification-usage.ts:10-50, src/core/models/notification-settings.ts:39-44
Management Logic Flow
When an administrator modifies settings via the API, the following sequence occurs:
The sequence ensures that only authorized administrators can modify the notification behavior for a specific chat.
Sources: src/api/admin.ts:162-205, examples/notification-usage.ts:14-25
Delivery and Scheduling
The bot processes notifications through a combination of manual triggers and automated cron jobs.
Scheduled Execution
The processScheduledNotifications function scans for pending tasks that have reached their scheduledAt time.
- Ingestion: The worker entry point receives a cron event.
- Validation: The system checks if the chat has
enabled: trueand is not currently inquietHours. - Generation: The service fetches the relevant data (e.g., from D1 or KV) and applies the
NotificationTemplate. - Delivery: The message is sent to the Telegram chat.
- Cleanup: Old notifications are removed periodically.
Sources: examples/notification-usage.ts:88-105, src/index.ts:740-760, src/core/models/notification-settings.ts:84-93
Administrative API Endpoints
The src/api/admin.ts file exposes endpoints for external management of the notification system.
| Endpoint | Method | Description |
|---|---|---|
/admin/api/notifications | GET | Retrieves current settings and available types for a chat. |
/admin/api/notifications | POST | Updates settings (requires chat administrator status). |
/api/criminal/analyze-test | POST | Manually triggers a criminal analysis test for diagnostic purposes. |
Sources: src/api/admin.ts:140-160, src/api/admin.ts:250-280, src/index.ts:144-160
Templates and Variables
Notifications use a templating system that supports conditional logic and dynamic variables.
// Example from src/core/models/notification-settings.ts:210-220
export interface NotificationTemplate {
type: NotificationType;
title: string;
template: string;
variables: string[];
description: string;
}
Common Template Variables
{{totalMessages}}: Total count of messages in the period.{{activeUsers}}: Number of unique users who sent messages.{{riskLevel}}: Calculated risk based on criminal violations.{{topUsers}}: A list of the most active or most frequent violators.{{peakHour}}: The hour of highest activity.
Sources: src/core/models/notification-settings.ts:240-300
Conclusion
The Automated Notifications System provides a robust framework for proactive chat monitoring. By combining Cloudflare Workers' cron triggers with Durable Objects for state management, the system ensures that chat administrators remain informed about user behavior and potential violations without manual intervention. The modular design of NotificationService allows for easy extension to new report types and delivery platforms.