IWF.TeleFlow.Framework 1.0.0-alpha.9

TeleFlow

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
• Documentation home
• English documentation
• Russian documentation
• Quickstart
• Configuration and secrets
• Recommended paths
• Package guide
• Support desk tutorial
• Enterprise guide
• Feature reference
• Roadmap

Community

• Telegram chat for quick questions, ideas, and alpha feedback.
• GitHub 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.
• Optional Generic Host integration through IWF.TeleFlow.Framework.Hosting.
• 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.

Most applications start from one scenario package. The lower-level packages are pulled in transitively and are documented separately for advanced use.

For a handler-based long polling bot:

dotnet add package IWF.TeleFlow.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:

<PackageReference Include="IWF.TeleFlow.Generators" Version="..." PrivateAssets="all" />

For direct Bot API access without the framework:

dotnet add package IWF.TeleFlow.Telegram --prerelease

For a .NET worker that should run TeleFlow through Microsoft.Extensions.Hosting, also install:

dotnet add package IWF.TeleFlow.Framework.Hosting --prerelease

You normally do not install IWF.TeleFlow.Framework.Core, IWF.TeleFlow.Framework, IWF.TeleFlow.Telegram.Client, IWF.TeleFlow.Telegram.Schema, or IWF.TeleFlow.Annotations directly. They are dependency or advanced packages behind the recommended entry points above.

First Bot

Create a console app, install the packages above, and set TELEFLOW_BOT_TOKEN:

export TELEFLOW_BOT_TOKEN=123456:token

PowerShell:

$env:TELEFLOW_BOT_TOKEN = "123456:token"

Replace Program.cs with this:

using TeleFlow.Telegram;
using TeleFlow.Annotations;
using TeleFlow.Framework.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
2. Configuration and secrets
3. Recommended paths
4. Handlers and routing
5. Callbacks and keyboards
6. State and wizard

If you already build production .NET services, read:

1. Packages
2. Configuration and secrets
3. Application model
4. Project structure
5. Dependency injection
6. Transports
7. Deployment
8. Performance and scaling
9. Versioning and releases
10. Enterprise guide

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.

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

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.