{"id":51202101,"url":"https://github.com/iwftech/teleflow","last_synced_at":"2026-06-30T03:00:37.602Z","repository":{"id":367340907,"uuid":"1279561622","full_name":"IWFTech/TeleFlow","owner":"IWFTech","description":"Explicit Telegram Bot API framework for .NET with generated handler metadata, state, callbacks, long polling, and webhooks.","archived":false,"fork":false,"pushed_at":"2026-06-29T01:53:22.000Z","size":1151,"stargazers_count":9,"open_issues_count":38,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-06-29T02:21:08.712Z","etag":null,"topics":["aot","bot-framework","csharp","dotnet","long-polling","nuget","source-generator","state-machine","telegram","telegram-bot","telegram-bot-api","webhooks"],"latest_commit_sha":null,"homepage":"https://iwftech.github.io/TeleFlow/","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/IWFTech.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-24T20:01:23.000Z","updated_at":"2026-06-29T01:45:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/IWFTech/TeleFlow","commit_stats":null,"previous_names":["iwftech/teleflow"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/IWFTech/TeleFlow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IWFTech%2FTeleFlow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IWFTech%2FTeleFlow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IWFTech%2FTeleFlow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IWFTech%2FTeleFlow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IWFTech","download_url":"https://codeload.github.com/IWFTech/TeleFlow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IWFTech%2FTeleFlow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34950330,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-30T02:00:05.919Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aot","bot-framework","csharp","dotnet","long-polling","nuget","source-generator","state-machine","telegram","telegram-bot","telegram-bot-api","webhooks"],"created_at":"2026-06-28T01:01:53.851Z","updated_at":"2026-06-30T03:00:37.572Z","avatar_url":"https://github.com/IWFTech.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TeleFlow\n\n[![.NET](https://img.shields.io/badge/.NET-10.0-512BD4)](https://dotnet.microsoft.com/)\n[![Telegram Bot API](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2FIWFTech%2FTeleFlow%2Fmain%2Fdocs%2Fbadges%2Ftelegram-bot-api.json)](https://core.telegram.org/bots/api-changelog)\n[![Telegram Chat](https://img.shields.io/badge/Telegram-chat-26A5E4?logo=telegram\u0026logoColor=white)](https://t.me/teleflow_chat)\n[![NuGet](https://img.shields.io/nuget/vpre/IWF.TeleFlow.Telegram.Framework.LongPolling?label=NuGet)](https://www.nuget.org/packages/IWF.TeleFlow.Telegram.Framework.LongPolling/)\n\n[![License](https://img.shields.io/github/license/IWFTech/TeleFlow)](LICENSE)\n[![CI](https://github.com/IWFTech/TeleFlow/actions/workflows/ci.yml/badge.svg)](https://github.com/IWFTech/TeleFlow/actions/workflows/ci.yml)\n[![CodeQL](https://github.com/IWFTech/TeleFlow/actions/workflows/codeql.yml/badge.svg)](https://github.com/IWFTech/TeleFlow/actions/workflows/codeql.yml)\n![GitHub last commit](https://img.shields.io/github/last-commit/IWFTech/TeleFlow)\n[![Downloads](https://img.shields.io/nuget/dt/IWF.TeleFlow.Telegram.Framework.LongPolling?label=downloads)](https://www.nuget.org/packages/IWF.TeleFlow.Telegram.Framework.LongPolling/)\n\n\n\nTeleFlow is an explicit Telegram bot framework for .NET.\n\nIt 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.\n\n\u003e Starts like a script. Grows like a system.\n\n## Documentation\n\nThe documentation is available as a GitHub Pages site and as Markdown in this repository.\n\n- [Documentation site](https://iwftech.github.io/TeleFlow/)\n- [Documentation home](docs/index.md)\n- [English documentation](docs/en/index.md)\n- [Russian documentation](docs/ru/index.md)\n- [Quickstart](docs/en/getting-started/quickstart.md)\n- [Configuration and secrets](docs/en/getting-started/configuration.md)\n- [Recommended paths](docs/en/getting-started/recommended-paths.md)\n- [Package guide](docs/en/getting-started/packages.md)\n- [Support desk tutorial](docs/en/tutorials/support-desk.md)\n- [Enterprise guide](docs/en/enterprise/index.md)\n- [Feature reference](docs/en/reference/attributes.md)\n- [Roadmap](docs/en/roadmap.md)\n\n## Community\n\n- [Telegram chat](https://t.me/teleflow_chat) for quick questions, ideas, and alpha feedback.\n- [GitHub Issues](https://github.com/IWFTech/TeleFlow/issues) for reproducible bugs and tracked feature requests.\n\n## What TeleFlow Gives You\n\n- Handler routing with attributes such as `[Command]`, `[Text]`, `[Callback]`, `[State]`, `[SceneStep]`, and media filters.\n- Build-time generated handler metadata through the `IWF.TeleFlow.Generators` package.\n- A deliberate failure when generated metadata is missing. No silent reflection fallback on the recommended path.\n- Direct Telegram Bot API access through `ITelegramClient` and generated `ctx.Bot.*Async` extension methods.\n- Message and callback helpers for common flows: answers, replies, edits, deletion, media, keyboards, and chat actions.\n- Typed callback payloads with compact callback data serialization.\n- State, state data, wizard navigation, and replaceable storage contracts.\n- Long polling and ASP.NET Core webhook framework adapters.\n- Raw long polling and raw webhook packages for applications that do not want the handler framework.\n- Normal .NET dependency injection for handlers, services, repositories, filters, storage, and infrastructure.\n\n## Install\n\nTeleFlow is currently published as a public alpha. Use `--prerelease` or pin an exact alpha version.\n\nFor a handler-based long polling bot:\n\n```bash\ndotnet add package IWF.TeleFlow.Telegram.Framework.LongPolling --prerelease\ndotnet add package IWF.TeleFlow.Generators --prerelease\ndotnet add package IWF.TeleFlow.Storage.Memory --prerelease\n```\n\nKeep the generator as a private build-time dependency:\n\n```xml\n\u003cPackageReference Include=\"IWF.TeleFlow.Generators\" Version=\"...\" PrivateAssets=\"all\" /\u003e\n```\n\nFor direct Bot API access without the framework:\n\n```bash\ndotnet add package IWF.TeleFlow.Telegram --prerelease\n```\n\n## First Bot\n\nCreate a console app, install the packages above, and set `TELEFLOW_BOT_TOKEN`:\n\n```bash\nexport TELEFLOW_BOT_TOKEN=123456:token\n```\n\nPowerShell:\n\n```powershell\n$env:TELEFLOW_BOT_TOKEN = \"123456:token\"\n```\n\nReplace `Program.cs` with this:\n\n```csharp\nusing TeleFlow.Telegram;\nusing TeleFlow.Annotations;\nusing TeleFlow.Core.Application;\n\nvar token = \"12345:BOT_TOKEN\";\nvar builder = TeleFlowApplication.CreateBuilder(args);\n\nbuilder.Services.AddTelegramBot(options =\u003e options.Token = token);\nbuilder.Services.AddTelegramHandlersFromAssembly(typeof(Program).Assembly);\nbuilder.Services.AddLongPolling();\n\nawait using var app = builder.Build();\nawait app.RunAsync();\n\npublic sealed class Handlers\n{\n    [Command(\"start\")]\n    public async Task Start(MessageContext ctx, CancellationToken ct)\n    {\n        await ctx.Message.AnswerAsync(\"Hello from TeleFlow\", ct);\n    }\n\n    [CommandTemplate(\"get_from {fromDate:string} {toDate:string} {count:int?}\")]\n    public async Task GetFrom(\n        MessageContext ctx,\n        string fromDate,\n        string toDate,\n        int? count,\n        CancellationToken ct)\n    {\n        await ctx.Message.AnswerAsync(\n            $\"Okay. Getting from {fromDate} to {toDate} with {count ?? 0}\",\n            ct);\n    }\n}\n```\n\n![Bot example](https://github.com/IWFTech/TeleFlow/blob/main/docs/assets/images%2Fbot_preview.png)\n\nThis 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.\n\n## Recommended Reading Order\n\nIf you are new to bot frameworks, read:\n\n1. [Quickstart](docs/en/getting-started/quickstart.md)\n2. [Configuration and secrets](docs/en/getting-started/configuration.md)\n3. [Recommended paths](docs/en/getting-started/recommended-paths.md)\n4. [Handlers and routing](docs/en/fundamentals/handlers-and-routing.md)\n5. [Callbacks and keyboards](docs/en/features/callbacks-and-keyboards.md)\n6. [State and wizard](docs/en/features/state-and-wizard.md)\n\nIf you already build production .NET services, read:\n\n1. [Packages](docs/en/getting-started/packages.md)\n2. [Configuration and secrets](docs/en/getting-started/configuration.md)\n3. [Application model](docs/en/fundamentals/application-model.md)\n4. [Project structure](docs/en/fundamentals/project-structure.md)\n5. [Dependency injection](docs/en/fundamentals/dependency-injection.md)\n6. [Transports](docs/en/transports/long-polling.md)\n7. [Deployment](docs/en/enterprise/deployment.md)\n8. [Performance and scaling](docs/en/enterprise/performance.md)\n9. [Versioning and releases](docs/en/enterprise/versioning.md)\n10. [Enterprise guide](docs/en/enterprise/index.md)\n\n## Project Status\n\nTeleFlow 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.\n\nPlanned framework work is tracked in the [roadmap](docs/en/roadmap.md).\n\nRuntime packages currently target `net10.0`. The `IWF.TeleFlow.Generators` package targets `netstandard2.0` because analyzers and source generators run inside the compiler.\n\n## Benchmarks\n\nThe repository includes an isolated BenchmarkDotNet project for no-network runtime measurements:\n\n- [Benchmark methodology and commands](benchmarks/README.md)\n\nBenchmark dependencies are intentionally kept outside `TeleFlow.sln` and do not affect normal library builds or package graphs.\n\n## License\n\nTeleFlow is released under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiwftech%2Fteleflow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiwftech%2Fteleflow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiwftech%2Fteleflow/lists"}