Admin API & Dashboard Endpoints
Relevant source files
The following files were used as context for generating this wiki page:
The Admin API and Dashboard provide a web-based interface for visualizing Telegram chat statistics, managing notification settings, and auditing message activity. The system restricts access to authenticated Telegram users and validates their membership in specific chats before disclosing data.
System Architecture and Routing
The system uses a centralized entry point in the main Worker script to route all requests starting with /admin.
Request Handling
The Cloudflare Worker intercept requests for /admin or sub-paths and passes them to the handleAdminRequest function. This function acts as a gateway for both HTML rendering and JSON API responses. If an unhandled exception occurs within the admin scope, the system returns a structured 503 error instead of a generic Worker failure page.
The error boundary ensures that raw error messages, which might contain sensitive payload data, are never surfaced to the user.
Sources: src/index.ts:74-100, tests/index.test.ts:511-532
Authentication and Authorization
Access control relies on the Telegram Login Widget and secure session cookies.
Authentication Flow
- Unauthenticated Access: The system serves a login page featuring the Telegram Login Widget.
- Login Callback: Telegram redirects the user to
/admin/loginwith authentication data. - Session Creation: The server validates the Telegram signature and creates a session cookie using
createTelegramSessionCookie. - Authorization: For every subsequent API request, the system verifies that the authenticated user is a member or administrator of the requested
chatIdusing the TelegramgetChatMemberAPI.
Sources: tests/index.test.ts:182-205, tests/index.test.ts:401-417
Dashboard UI Components
The dashboard is rendered as a Single Page Application (SPA) shell containing interactive charts and data tables.
Data Visualizations
The UI uses Chart.js to render several metric types:
- Activity Charts: Displays daily message counts and active user peaks.
- Hourly Activity: Shows average activity by hour, adjustable via a timezone selector persisted in
localStorage. - Profanity Metrics: Visualizes the rate of profanity relative to total words.
- Participant Rhythm: A heatmap grid showing typical activity levels (inactive, active, talkative) by day of the week and time bucket.
UI Features Table
| Feature | Implementation | Description |
|---|---|---|
| Draggable Layout | DragHandle / localStorage | Allows users to reorder and resize dashboard sections. |
| Theme Toggle | Data Attributes | Supports System, Light (Day), and Dark (Night) modes. |
| Timezone Shift | JS Math / Storage | Adjusts UTC hourly stats to local user time. |
| Heatmaps | HTML Tables / CSS | Provides a visual "rhythm" of chat participation. |
Sources: src/api/admin-html.ts:18-100, src/api/admin-html.ts:780-850, tests/admin-html.test.ts:60-100
Admin API Endpoints
The API provides JSON endpoints for fetching data used by the dashboard shell.
Available Endpoints
| Endpoint | Method | Parameters | Description |
|---|---|---|---|
/admin/api/chats | GET | None | Lists all chats where the user is a member. |
/admin/api/chat | GET | chatId, period, from, to | Returns detailed statistics for a specific chat. |
/admin/api/notifications | GET | chatId | Retrieves current notification settings. |
/admin/api/notifications | POST | chatId, JSON Body | Updates notification settings (Admin only). |
Data Retrieval Logic
When statistics are requested, the system performs the following sequence:
- Membership Validation: Checks if the user has access to the
chatId. - D1 Query: Attempts to read aggregated statistics from the D1 database.
- Legacy Fallback: If D1 data is unavailable for the requested period, the system returns a
503 ADMIN_UNAVAILABLEorHISTORICAL_STATS_NOT_READYerror rather than scanning KV namespaces directly, ensuring performance stability. - Privacy Scrubbing: Returns a privacy-safe participant timeline for regular members, omitting raw user identifiers and specific message counts where necessary.
Sources: tests/index.test.ts:227-250, tests/index.test.ts:420-435, tests/index.test.ts:327-353
Notification Management
The system allows chat administrators to configure automatic bot reports.
Configuration Options
Users can toggle various notification categories:
- Daily/Weekly/Monthly Summaries: AI-generated text overviews.
- Profanity Reports: Alerts for detected vulgar language.
- Criminal Code Alerts: Notifications for high-risk message analysis.
Persistence Flow
Only users with "administrator" or "creator" status in the Telegram chat are permitted to modify these settings.
Sources: tests/index.test.ts:548-570, src/api/admin-html.ts:1174-1200
Summary
The Admin API and Dashboard constitute a secure management layer for the bot. By separating HTML rendering from data retrieval and enforcing strict Telegram-based authorization, the system provides detailed insights into chat behavior while maintaining user privacy and system performance through D1-backed aggregation.