TelegramBotKit 0.3.0

TelegramBotKit

TelegramBotKit is a lightweight toolkit for building Telegram bots on .NET with a structured update pipeline, typed handlers, and simple command routing.

Packages

• TelegramBotKit — core pipeline, commands, messaging.
• TelegramBotKit.Hosting — polling/hosting integration.
• TelegramBotKit.Routing — optional ASP.NET-style Use* routing sugar.
• TelegramBotKit.Generators — optional Roslyn source generator for compile-time AddCommands() registration.

Features

• Middleware pipeline for update processing.
• Typed update payload handlers (IUpdatePayloadHandler<TPayload>).
• Message/text/callback commands with attributes.
• WaitForUserResponse helper for request/response flows.
• IMessageSender facade for sending messages.
• Optional queued sender to reduce rate-limit errors.

Installation

dotnet add package TelegramBotKit
dotnet add package TelegramBotKit.Hosting
# optional
dotnet add package TelegramBotKit.Routing
# optional (compile-time AddCommands)
dotnet add package TelegramBotKit.Generators

Quick start (polling)

1. Add configuration.

Create appsettings.json:

{
  "TelegramBotKit": {
    "Token": "PUT_YOUR_BOT_TOKEN_HERE",
    "Polling": {
      "MaxDegreeOfParallelism": 4,
      "Limit": 100,
      "TimeoutSeconds": 10,
      "AllowedUpdates": []
    }
  }
}

2. Create a host.

using Microsoft.Extensions.Hosting;
using TelegramBotKit.DependencyInjection;
using TelegramBotKit.Hosting;

var builder = Host.CreateApplicationBuilder(args);

builder.Configuration.AddJsonFile("appsettings.json", optional: false, reloadOnChange: true);

var bot = builder.Services.AddTelegramBotKit(opt =>
{
    builder.Configuration.GetSection("TelegramBotKit").Bind(opt);
});

// Registers attributed commands.
// If TelegramBotKit.Generators is installed, this is compile-time.
// Otherwise it falls back to reflection-based discovery.
builder.Services.AddCommands();

bot.UseQueuedMessageSender();

builder.Services.AddTelegramBotKitPolling();

var host = builder.Build();
await host.RunAsync();

3. Add a command.

using Telegram.Bot.Types;
using TelegramBotKit.Commands;
using TelegramBotKit.Messaging;

namespace MyBot.Commands;

[MessageCommand("/start")]
public sealed class StartCommand : IMessageCommand
{
    public Task HandleAsync(Message message, BotContext ctx)
    {
        return ctx.Sender.SendText(message.Chat.Id, new SendText
        {
            Text = "Hello."
        }, ctx.CancellationToken);
    }
}

Documentation

• docs/quickstart.md
• docs/commands-and-routing.md
• docs/middleware.md
• docs/hosting.md
• docs/public-api.md

Running the sample

dotnet run --project samples/TelegramBotKit.Sample.ConsolePolling