PolyBot: Attribute-Driven Telegram Bot Framework

PolyBot is a Roslyn source-generator-powered routing framework for Telegram.Bot. Write decorated handler methods instead of switch statements — the generator does the rest.

PolyBot turns your Telegram bot logic into clean, attribute-decorated handler methods. A Roslyn source generator compiles them at build time into a hard-coded, optimized BotRouter — no reflection, no runtime overhead, and full dependency injection out of the box.

Quickstart

Build and run your first PolyBot bot in minutes with a working code example.

Installation

Add PolyBot to your .NET project and wire up the source generator.

Core Concepts

Understand how handlers, routing, filters, and DI work together.

API Reference

Full reference for every attribute, interface, and configuration option.

Why PolyBot?

Traditional Telegram.Bot bots require a central HandleUpdateAsync with nested switch statements over Update.Type. PolyBot eliminates that entirely — you write one handler method per intent, and the framework wires everything up at compile time.

Source-Generated Router

Roslyn generates a BotRouter from your handler attributes at compile time. Zero reflection at runtime.

Full DI Support

Handler parameters resolve automatically from the service container — inject anything from ITelegramBotClient to your own services.

Finite State Machines

Built-in FSM support with [State<TEnum>] and pluggable IStateStorage for multi-step conversations.

Inline Awaits

Suspend a handler mid-conversation and resume when the next matching update arrives — without blocking the polling loop.

Callback Patterns

Route callback queries by template: [Pattern("item:{id}:{action}")] with typed [Arg] extraction.

Built-in Testing

Token-free in-memory test harness via UpdateMocker — no network, no real bot token needed.

Get Started

1. Install the NuGet package

   Add PolyBot to your .NET project. The source generator is bundled as an analyzer.

   dotnet add package PolyBot
   
2. Write your first handler

   Decorate a static method with a handler attribute and return Result.

   Program.cs

   using PolyBot.Attributes;
   using PolyBot.Routing;
   using Telegram.Bot.Types;
   
   public sealed partial class BotHandlers
   {
       [MessageHandler]
       [Command(Aliases = ["start"], Description = "Start the bot")]
       public static async Task<Result> Start(Message msg, ITelegramBotClient bot, CancellationToken ct)
       {
           await bot.SendMessage(msg.Chat.Id, "Hello from PolyBot!", cancellationToken: ct);
           return Result.Handled();
       }
   }
   
3. Register and run

   Create a PolyBotClient, register the generated router, and start polling.

   Program.cs

   using PolyBot;
   
   PolyBotClient client = new PolyBotClient(new PolyBotOptions { BotToken = "<your-token>" });
   client.Services.AddPolyBotRouter(); // generated by the source generator
   await client.RunPollingAsync();
   

AddPolyBotRouter() is generated at compile time by the PolyBot source generator — it will appear after your first build. See Installation for project setup details.