Getting Started & Setup

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• README.md
• src/index.ts
• GEMINI.md
• CLAUDE.md
• tests/integration/README.md

The Telegram Stats Bot provides message collection, storage, and analysis within the Cloudflare Workers ecosystem. It stores messages in Cloudflare KV for seven days, tracks user activity via Durable Objects, and generates summaries using Workers AI or OpenAI. This guide details the initialization, configuration, and deployment procedures required to establish a functional bot instance.

Sources: AGENTS.md:3-5, README.md:3-13

Project Prerequisites

You must have the following tools and accounts ready before starting the setup:

• A Cloudflare account with Workers and D1 enabled.
• A Telegram bot token obtained from BotFather.
• Node.js environment with npm installed.

Sources: README.md:46-52, AGENTS.md:15-18

Core Installation Steps

The setup process involves installing dependencies, provisioning Cloudflare resources, and configuring secret tokens.

1. Install Dependencies: Execute npm install to download necessary packages.
2. Resource Provisioning: Run the ./setup.sh script. This script creates the required KV namespaces and the D1 database.
3. Database Initialization: Apply the initial D1 migrations using npx wrangler d1 migrations apply summaries.
4. Configuration: Copy the IDs generated by the setup script into the wrangler.jsonc file.

Sources: README.md:104-114, AGENTS.md:52-55

Deployment Workflow

The following diagram illustrates the high-level deployment sequence:

The diagram shows the linear progression from local installation to final command registration.
Sources: README.md:104-122

Environment Variables and Secrets

The bot requires specific secrets to interact with APIs and secure its webhook. You must set these using the wrangler secret put command.

Secret Name	Description	Source
TOKEN	Telegram bot token for API communication.	AGENTS.md:58
SECRET	Webhook HMAC header for request validation.	AGENTS.md:59
OPENAI_API_KEY	Key for OpenAI summary and analysis providers.	README.md:112
OPENAI_PREMIUM_API_KEY	Optional key for high-tier OpenAI models.	README.md:113

Sources: AGENTS.md:57-59, README.md:110-114

System Configuration

Global settings are managed in wrangler.jsonc. These parameters define which AI models and providers the bot uses for various features.

• Providers: Set SUMMARY_PROVIDER, PROFANITY_PROVIDER, and CRIMINAL_PROVIDER to cloudflare or openai.
• Models: Define specific models via OPENAI_MODEL or CLOUDFLARE_MODEL.
• AI Tuning: Configure token limits and sampling via *_MAX_TOKENS, *_TEMPERATURE, and *_TOP_P.

Sources: README.md:115-119

Webhook Authentication Logic

The bot validates incoming requests to ensure they originate from Telegram. It checks both the token in the URL path and the X-Telegram-Bot-Api-Secret-Token header.

The sequence diagram demonstrates the authentication gateway in src/index.ts that protects the webhook endpoint.
Sources: src/index.ts:166-218

Development and Testing

The project uses vitest for both unit and integration testing. Development scripts are defined in package.json.

• Local Server: Run npx wrangler dev --local to start a local development environment.
• Run Tests: Execute npm test to run the test suite. You must run tests before committing changes.
• Integration Tests: Located in tests/integration/, these cover E2E flows including command handling and message processing.

Sources: AGENTS.md:46-51, GEMINI.md:27, tests/integration/README.md:5-30

Project Layout

The repository follows a strict structure to separate documentation, scripts, and source code.

• docs/: Contains guides, operations notes, and feature design.
• scripts/: Holds utility and fix scripts (e.g., scripts/fixes/).
• src/core/: Shared modules and environment handling.
• src/features/: Modular implementations of bot features like stats and summaries.

Sources: AGENTS.md:21-43, GEMINI.md:14-22

The Telegram History Bot is ready for operation once the Cloudflare resources are bound, secrets are configured, and the webhook is registered with Telegram. Proper setup ensures that data remains secure and costs are minimized within the Cloudflare Worker execution limits.

Sources: AGENTS.md:6-10, README.md:120-123