IWF.TeleFlow.Storage.Memory 0.1.0-alpha.1

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 repository documentation is split like a small product site and is ready to be moved to GitHub Pages later.

• Documentation home
• English documentation
• Russian documentation
• Quickstart
• Configuration and secrets
• Recommended paths
• Package guide
• Support desk tutorial
• Enterprise guide
• Feature reference
• Roadmap

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

For a handler-based long polling bot:

dotnet add package IWF.TeleFlow.Telegram.Framework.LongPolling
dotnet add package IWF.TeleFlow.Generators
dotnet add package IWF.TeleFlow.Storage.Memory

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

First Bot

using TeleFlow.Annotations;
using TeleFlow.Core.Application;
using TeleFlow.Storage.Memory;
using TeleFlow.Telegram;

var token = Environment.GetEnvironmentVariable("TELEFLOW_BOT_TOKEN")
    ?? throw new InvalidOperationException("TELEFLOW_BOT_TOKEN is not set.");

var builder = TeleFlowApplication.CreateBuilder(args);

builder.Services.AddTelegramBot(options => options.Token = token);
builder.Services.AddMemoryStateStorage();
builder.Services.AddTelegramHandlersFromAssembly(typeof(Program).Assembly);
builder.Services.AddLongPolling();

await using var app = builder.Build();
await app.RunAsync();

public sealed class StartHandler
{
    [Command("start")]
    public Task Handle(MessageContext ctx, CancellationToken ct)
    {
        return ctx.Message.AnswerAsync("Hello from TeleFlow.", 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.

License

TeleFlow is released under the MIT License.