Curiosus.TelegramBot 3.0.0

Curiosus.TelegramBot

Infrastructure library for building Telegram bots on .NET: command dispatching, multi-step state management, update queue with persistence, and simple chat authentication.

Renamed: formerly Markeli.TelegramBot. Since 2.0.0 the package is published as Curiosus.TelegramBot by curiosus-dev. To migrate, update the package reference and replace the Markeli.TelegramBot namespace.

Why use it

Telegram.Bot gives you the Bot API; a real bot also needs the plumbing around it. Curiosus.TelegramBot provides it, so a bot is a set of command handlers and nothing else:

• Commands, not update loops — implement ITelegramBotCommandHandler per command, routing by command text and message type is done for you.
• Conversations out of the box — return a state and the next message of the chat comes back to the same handler.
• Safe under load — bounded parallelism, optional per-key locks for commands that must not run concurrently, and pending updates survive a graceful restart when queue persistence is on.
• Private bots in one line — allowed chat IDs and a password challenge for everyone else.
• Zero startup code — the bot runs as an IHostedService registered by AddTelegramBotInfrastructure.

Features

• Command dispatching — register handlers via ITelegramBotCommandHandler, route updates by command text and supported update/message types.
• State management — multi-step conversational commands with in-memory state cache (TelegramBotCommandStateBase).
• Update queue — thread-safe queue with configurable parallelism and optional disk persistence on shutdown.
• Authentication — simple password-based chat verification with allowed chat ID filtering.
• Built-in /help command — opt-in handler that lists all registered commands via AddHelpCommand().
• Rich message support — rich formatted messages (Bot API 10.1) are routed like plain text via Update.GetMessageText(), with structured blocks available through Update.GetRichBlocks().
• DI integration — AddTelegramBotInfrastructure / AddTelegramBotCommandHandler<T> extensions for IServiceCollection.

Quick start

Prerequisites

• .NET 9.0 or later
• Telegram Bot API token — create one via BotFather

Installation

dotnet add package Curiosus.TelegramBot

Usage

Register the infrastructure and command handlers in your DI container:

builder.Services.AddTelegramBotInfrastructure(new TelegramBotOptions
{
    ApiToken = "BOT_TOKEN",
    Password = "secret",
    AllowedChatIds = new[] { 123456L }
});

builder.Services.AddTelegramBotCommandHandler<PingCommandHandler>();
builder.Services.AddHelpCommand();

Implement a command handler:

public class PingCommandHandler : ITelegramBotCommandHandler
{
    public string CommandName => "Ping";
    public string CommandText => "/ping";
    public IReadOnlySet<UpdateType> SupportedUpdateTypes => new HashSet<UpdateType> { UpdateType.Message };
    public IReadOnlySet<MessageType> SupportedMessageTypes => TelegramBotMessageTypes.TextOrRich;

    public async Task<TelegramBotCommandProcessingResult> ProcessCommandAsync(
        ITelegramBotClient telegramBotClient, Update telegramUpdate,
        ITelegramBotCommandState? commandState, CancellationToken cancellationToken)
    {
        await telegramBotClient.SendMessage(
            telegramUpdate.Message!.Chat.Id, "pong", cancellationToken: cancellationToken);
        return TelegramBotCommandProcessingResult.WithoutState();
    }
}

The bot starts automatically as an IHostedService — no extra startup code required.

Architecture

Telegram API
    │ polling via Telegram.Bot
    ▼
TelegramBotUpdateDispatcher          (IHostedService — starts polling, runs dispatch loop)
    ├─ on receive ──► TelegramUpdateQueue.Enqueue()
    └─ dispatch loop
         ├─ TelegramUpdateQueue.Take()
         ├─ ResolveCommand()           (state-cache aware routing)
         ├─ TryAcquireLock()           (optional per-key exclusive lock)
         ├─ SemaphoreSlim              (MaxDegreeOfParallelism)
         └─► TelegramUpdateProcessor.ProcessAsync()
              ├─ Auth gate             (AllowedChatIds / password challenge)
              ├─ Message type guard
              ├─ State lookup          (TelegramBotCommandStateCache)
              ├─ ITelegramBotCommandHandler.ProcessCommandAsync()
              └─ State update/remove   (based on result.State)

Updates are polled, enqueued into a thread-safe BlockingCollection<Update>, and dispatched to handlers with configurable concurrency (MaxDegreeOfParallelism, default 10). If a handler returns state, the next message from that chat is routed to the same handler automatically.

Configuration

All settings are passed via TelegramBotOptions:

HTTP proxy

HttpProxyOptions fields:

services.AddTelegramBotInfrastructure(new TelegramBotOptions
{
    ApiToken = "BOT_TOKEN",
    Password = "secret",
    HttpProxy = new HttpProxyOptions
    {
        Url = "http://proxy.example.com:8080",
        Username = "user",
        Password = "pass"
    }
});

Authentication flow

Chats listed in AllowedChatIds are authorized automatically. When an unknown chat sends a message:

1. The bot replies with "Hi! To use this bot, please, send a verification password."
2. If the user sends the correct Password, the chat is added to the allowed set for the lifetime of the process. Authorization is stored in memory only and resets on application restart.
3. If incorrect, the bot replies "Incorrect password! Please, try again."

Multi-step commands

Return WithSimpleState() from ProcessCommandAsync to keep the conversation going — the next message from that chat will be routed to the same handler with the previous state:

public class GreetCommandHandler : ITelegramBotCommandHandler
{
    public string CommandName => "Greet";
    public string CommandText => "/greet";
    public IReadOnlySet<UpdateType> SupportedUpdateTypes => new HashSet<UpdateType> { UpdateType.Message };
    public IReadOnlySet<MessageType> SupportedMessageTypes => TelegramBotMessageTypes.TextOrRich;

    public async Task<TelegramBotCommandProcessingResult> ProcessCommandAsync(
        ITelegramBotClient telegramBotClient, Update telegramUpdate,
        ITelegramBotCommandState? commandState, CancellationToken cancellationToken)
    {
        var chatId = telegramUpdate.Message!.Chat.Id;

        if (commandState is null)
        {
            await telegramBotClient.SendMessage(
                chatId, "What is your name?", cancellationToken: cancellationToken);
            return TelegramBotCommandProcessingResult.WithSimpleState();
        }

        var name = telegramUpdate.GetMessageText();
        await telegramBotClient.SendMessage(
            chatId, $"Hello, {name}!", cancellationToken: cancellationToken);
        return TelegramBotCommandProcessingResult.WithoutState();
    }
}

For custom state data, implement ITelegramBotCommandState (or extend TelegramBotCommandStateBase for timestamps) and return it via new TelegramBotCommandProcessingResult { State = myState }.

The user can abort a multi-step flow at any time by sending another /command — it will be matched to the new handler instead.

Rich messages

A rich formatted message (Bot API 10.1) carries its content in Message.RichMessage and leaves Message.Text unset, so it arrives as MessageType.RichMessage rather than MessageType.Text.

Receiving. Declare TelegramBotMessageTypes.TextOrRich in SupportedMessageTypes to accept both, and read the text through Update.GetMessageText(), which falls back to flattening the rich blocks into plain text (blocks joined with newlines, inline formatting dropped). A handler that declares only MessageType.Text and reads Message.Text directly will reject rich messages.

For the structure itself, use Update.GetRichBlocks():

var blocks = telegramUpdate.GetRichBlocks();
if (blocks is not null)
{
    foreach (var table in blocks.OfType<RichBlockTable>())
    {
        // ...
    }
}

Sending. No library API is involved — handlers receive ITelegramBotClient directly and call Telegram.Bot themselves:

await telegramBotClient.SendRichMessage(chatId, new InputRichMessage
{
    Blocks =
    [
        new InputRichBlockSectionHeading { Text = new RichTextText { Text = "Daily report" } },
        new InputRichBlockParagraph { Text = new RichTextText { Text = "All systems nominal." } }
    ]
}, cancellationToken: cancellationToken);

InputRichMessage accepts exactly one of Blocks, Html, or Markdown. Use SendRichMessageDraft to stream a partial message while it is still being generated.

Concurrent lock keys

Override TryGetLockKey to prevent parallel execution of the same command for a specific context (e.g., per chat):

public bool TryGetLockKey(Update telegramUpdate, out string? lockKey)
{
    lockKey = $"my_command_{telegramUpdate.Message?.Chat.Id}";
    return true;
}

When a lock key is active, conflicting updates are re-enqueued and retried. This method has a default implementation that returns false (no locking), so most handlers don't need to override it.

Build

dotnet build
dotnet test

The project uses Cake for build automation, the same pipeline runs locally and on CI:

dotnet tool restore                   # once: Cake and ReportGenerator
dotnet cake                           # Clean + build + tests
dotnet cake --target=CoverageReport   # Tests with coverage + HTML report in ./artifacts/coverage-report/
dotnet cake --target=Pack             # NuGet package in ./artifacts/packages/

Build scripts and settings are shared with the other Curiosus libraries via curiosus-dev/dotnet-tools.

Packages are restored exclusively from nuget.org: the repository-level nuget.config clears any inherited source and maps every package pattern to nuget.org, so restore behaves identically on any machine.

Available packages

Package	Version	Downloads	Coverage
Curiosus.TelegramBot

License

MIT