TeleFlow Documentation

TeleFlow is a Telegram bot framework for .NET that keeps the first handler simple and the grown application explicit.

The core idea is direct: your bot should not become a black box just because the framework is convenient. TeleFlow keeps handler code close to normal C#, uses normal dependency injection, exposes the Telegram client directly, and moves handler metadata generation to build time on the recommended path.

Start Here

• Quickstart: build a minimal long polling bot.
• Configuration and secrets: read token and webhook settings through normal .NET configuration.
• Recommended paths: choose the right learning path for your level.
• Package guide: understand what to install and why.
• Support desk tutorial: a realistic bot with DI, state, callbacks, and admin actions.
• Roadmap: planned framework work that is not part of the current public API yet.
• Russian documentation: same documentation in Russian.

Learning Paths

First Bot

For trainees and juniors who want to get something working without being buried in infrastructure:

1. Quickstart
2. Configuration and secrets
3. Handlers and routing
4. Callbacks and keyboards
5. State and wizard
6. Support desk tutorial

Production Bot

For developers who already understand .NET services and want correct project shape:

1. Application model
2. Configuration and secrets
3. Project structure
4. Dependency injection
5. Telegram client and schema
6. Errors and diagnostics
7. Testing

Enterprise Bot

For teams that care about predictable runtime behavior, ownership boundaries, deployment, and future maintenance:

1. Enterprise guide
2. Deployment
3. Performance and scaling
4. Versioning and releases
5. Production checklist
6. Architecture notes
7. Generated registration
8. Custom storage

Documentation Map

Getting Started

• Quickstart
• Configuration and secrets
• Recommended paths
• Packages

Tutorials

• Support desk bot

Fundamentals

• Application model
• Project structure
• Handlers and routing
• Filters
• Dependency injection
• Cancellation

Features

• Telegram client and schema
• Callbacks and keyboards
• State and wizard
• Roles and chat members
• Errors and diagnostics

Transports

• Long polling
• Webhooks
• Raw transports

Advanced

• Generated registration
• Custom storage
• Middleware and rate limiting
• Testing

Enterprise

• Enterprise guide
• Deployment
• Performance and scaling
• Versioning and releases
• Architecture notes
• Production checklist

Reference

• Attributes
• Options and extension points
• Troubleshooting

Planning

• Roadmap

Philosophy

TeleFlow exists for the moment when a simple Telegram bot becomes an application.

It should remain easy to start:

• one console app;
• one command handler;
• one token;
• one long polling transport.

It should also remain honest when the project grows:

• no hidden reflection fallback on the recommended registration path;
• no requirement to wrap every Telegram call in a framework abstraction;
• no special service container;
• no fake enterprise story based only on naming.

The design preference is simple: explicit behavior, predictable runtime, small public contracts, and extension points only where replacement is a real use case.

Current Scope

The current repository includes:

• Telegram Bot API client and generated schema models;
• generated client method extension methods;
• handler framework for messages, callbacks, and chat member updates;
• command, text, template, regex, media, callback, state, scene, role, and custom filter attributes;
• typed callback payloads through [CallbackData] and [Callback<TPayload>];
• inline keyboards, reply keyboards, keyboard removal, force reply, and chat actions;
• state, state data, wizard navigation, and memory storage;
• long polling and ASP.NET Core webhook adapters;
• raw long polling and raw webhook packages;
• generated handler registration, explicit direct registration, and explicit reflection registration;
• middleware, update processor, update source, dispatcher, storage, callback serializer, and client replacement points.