https://github.com/iwftech/teleflow
Explicit Telegram Bot API framework for .NET with generated handler metadata, state, callbacks, long polling, and webhooks.
https://github.com/iwftech/teleflow
aot bot-framework csharp dotnet long-polling nuget source-generator state-machine telegram telegram-bot telegram-bot-api webhooks
Last synced: about 8 hours ago
JSON representation
Explicit Telegram Bot API framework for .NET with generated handler metadata, state, callbacks, long polling, and webhooks.
- Host: GitHub
- URL: https://github.com/iwftech/teleflow
- Owner: IWFTech
- License: mit
- Created: 2026-06-24T20:01:23.000Z (6 days ago)
- Default Branch: main
- Last Pushed: 2026-06-29T01:53:22.000Z (1 day ago)
- Last Synced: 2026-06-29T02:21:08.712Z (1 day ago)
- Topics: aot, bot-framework, csharp, dotnet, long-polling, nuget, source-generator, state-machine, telegram, telegram-bot, telegram-bot-api, webhooks
- Language: C#
- Homepage: https://iwftech.github.io/TeleFlow/
- Size: 1.1 MB
- Stars: 9
- Watchers: 3
- Forks: 0
- Open Issues: 38
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# TeleFlow
[](https://dotnet.microsoft.com/)
[](https://core.telegram.org/bots/api-changelog)
[](https://t.me/teleflow_chat)
[](https://www.nuget.org/packages/IWF.TeleFlow.Telegram.Framework.LongPolling/)
[](LICENSE)
[](https://github.com/IWFTech/TeleFlow/actions/workflows/ci.yml)
[](https://github.com/IWFTech/TeleFlow/actions/workflows/codeql.yml)
[](https://www.nuget.org/packages/IWF.TeleFlow.Telegram.Framework.LongPolling/)
TeleFlow is an explicit Telegram bot framework for .NET.
It is built for the normal lifecycle of a Telegram bot: a first command, then callbacks, state, role checks, background services, retries, storage, diagnostics, deployment, and a codebase that still needs to be readable after it grows.
> Starts like a script. Grows like a system.
## Documentation
The documentation is available as a GitHub Pages site and as Markdown in this repository.
- [Documentation site](https://iwftech.github.io/TeleFlow/)
- [Documentation home](docs/index.md)
- [English documentation](docs/en/index.md)
- [Russian documentation](docs/ru/index.md)
- [Quickstart](docs/en/getting-started/quickstart.md)
- [Configuration and secrets](docs/en/getting-started/configuration.md)
- [Recommended paths](docs/en/getting-started/recommended-paths.md)
- [Package guide](docs/en/getting-started/packages.md)
- [Support desk tutorial](docs/en/tutorials/support-desk.md)
- [Enterprise guide](docs/en/enterprise/index.md)
- [Feature reference](docs/en/reference/attributes.md)
- [Roadmap](docs/en/roadmap.md)
## Community
- [Telegram chat](https://t.me/teleflow_chat) for quick questions, ideas, and alpha feedback.
- [GitHub Issues](https://github.com/IWFTech/TeleFlow/issues) for reproducible bugs and tracked feature requests.
## What TeleFlow Gives You
- Handler routing with attributes such as `[Command]`, `[Text]`, `[Callback]`, `[State]`, `[SceneStep]`, and media filters.
- Build-time generated handler metadata through the `IWF.TeleFlow.Generators` package.
- A deliberate failure when generated metadata is missing. No silent reflection fallback on the recommended path.
- Direct Telegram Bot API access through `ITelegramClient` and generated `ctx.Bot.*Async` extension methods.
- Message and callback helpers for common flows: answers, replies, edits, deletion, media, keyboards, and chat actions.
- Typed callback payloads with compact callback data serialization.
- State, state data, wizard navigation, and replaceable storage contracts.
- Long polling and ASP.NET Core webhook framework adapters.
- Raw long polling and raw webhook packages for applications that do not want the handler framework.
- Normal .NET dependency injection for handlers, services, repositories, filters, storage, and infrastructure.
## Install
TeleFlow is currently published as a public alpha. Use `--prerelease` or pin an exact alpha version.
For a handler-based long polling bot:
```bash
dotnet add package IWF.TeleFlow.Telegram.Framework.LongPolling --prerelease
dotnet add package IWF.TeleFlow.Generators --prerelease
dotnet add package IWF.TeleFlow.Storage.Memory --prerelease
```
Keep the generator as a private build-time dependency:
```xml
```
For direct Bot API access without the framework:
```bash
dotnet add package IWF.TeleFlow.Telegram --prerelease
```
## First Bot
Create a console app, install the packages above, and set `TELEFLOW_BOT_TOKEN`:
```bash
export TELEFLOW_BOT_TOKEN=123456:token
```
PowerShell:
```powershell
$env:TELEFLOW_BOT_TOKEN = "123456:token"
```
Replace `Program.cs` with this:
```csharp
using TeleFlow.Telegram;
using TeleFlow.Annotations;
using TeleFlow.Core.Application;
var token = "12345:BOT_TOKEN";
var builder = TeleFlowApplication.CreateBuilder(args);
builder.Services.AddTelegramBot(options => options.Token = token);
builder.Services.AddTelegramHandlersFromAssembly(typeof(Program).Assembly);
builder.Services.AddLongPolling();
await using var app = builder.Build();
await app.RunAsync();
public sealed class Handlers
{
[Command("start")]
public async Task Start(MessageContext ctx, CancellationToken ct)
{
await ctx.Message.AnswerAsync("Hello from TeleFlow", ct);
}
[CommandTemplate("get_from {fromDate:string} {toDate:string} {count:int?}")]
public async Task GetFrom(
MessageContext ctx,
string fromDate,
string toDate,
int? count,
CancellationToken ct)
{
await ctx.Message.AnswerAsync(
$"Okay. Getting from {fromDate} to {toDate} with {count ?? 0}",
ct);
}
}
```
This example uses generated assembly registration. If the `IWF.TeleFlow.Generators` package is not referenced by the application project, `AddTelegramHandlersFromAssembly(...)` fails during startup with a clear configuration error.
## Recommended Reading Order
If you are new to bot frameworks, read:
1. [Quickstart](docs/en/getting-started/quickstart.md)
2. [Configuration and secrets](docs/en/getting-started/configuration.md)
3. [Recommended paths](docs/en/getting-started/recommended-paths.md)
4. [Handlers and routing](docs/en/fundamentals/handlers-and-routing.md)
5. [Callbacks and keyboards](docs/en/features/callbacks-and-keyboards.md)
6. [State and wizard](docs/en/features/state-and-wizard.md)
If you already build production .NET services, read:
1. [Packages](docs/en/getting-started/packages.md)
2. [Configuration and secrets](docs/en/getting-started/configuration.md)
3. [Application model](docs/en/fundamentals/application-model.md)
4. [Project structure](docs/en/fundamentals/project-structure.md)
5. [Dependency injection](docs/en/fundamentals/dependency-injection.md)
6. [Transports](docs/en/transports/long-polling.md)
7. [Deployment](docs/en/enterprise/deployment.md)
8. [Performance and scaling](docs/en/enterprise/performance.md)
9. [Versioning and releases](docs/en/enterprise/versioning.md)
10. [Enterprise guide](docs/en/enterprise/index.md)
## Project Status
TeleFlow is in active development. The documentation describes APIs that exist in the current repository. Planned features belong in roadmap documents, not in user-facing API documentation.
Planned framework work is tracked in the [roadmap](docs/en/roadmap.md).
Runtime packages currently target `net10.0`. The `IWF.TeleFlow.Generators` package targets `netstandard2.0` because analyzers and source generators run inside the compiler.
## Benchmarks
The repository includes an isolated BenchmarkDotNet project for no-network runtime measurements:
- [Benchmark methodology and commands](benchmarks/README.md)
Benchmark dependencies are intentionally kept outside `TeleFlow.sln` and do not affect normal library builds or package graphs.
## License
TeleFlow is released under the MIT License.