> ## Documentation Index
> Fetch the complete documentation index at: https://poly-bot.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://poly-bot.mintlify.site/quickstart.md)**
>
> Build and run your first PolyBot bot in minutes with a working code example.

> **[Installation](https://poly-bot.mintlify.site/installation.md)**
>
> Add PolyBot to your .NET project and wire up the source generator.

> **[Core Concepts](https://poly-bot.mintlify.site/concepts/handlers.md)**
>
> Understand how handlers, routing, filters, and DI work together.

> **[API Reference](https://poly-bot.mintlify.site/reference/attributes.md)**
>
> 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.

```bash theme={null}
dotnet add package PolyBot
```

**2. Write your first handler**

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

```csharp Program.cs theme={null}
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.

```csharp Program.cs theme={null}
using PolyBot;

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

> [!NOTE]
>
> `AddPolyBotRouter()` is generated at compile time by the PolyBot source generator — it will appear after your first build. See [Installation](https://poly-bot.mintlify.site/installation.md) for project setup details.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.