TBotPlatform 2.3.0-beta1

.NET 8.0 This package targets .NET 8.0. The package is compatible with this framework or higher.
This is a prerelease version of TBotPlatform.
There is a newer prerelease version of this package available.
See the version list below for details. 
dotnet add package TBotPlatform --version 2.3.0-beta1
                    


                    

                
NuGet\Install-Package TBotPlatform -Version 2.3.0-beta1
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="TBotPlatform" Version="2.3.0-beta1" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="TBotPlatform" Version="2.3.0-beta1" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="TBotPlatform" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add TBotPlatform --version 2.3.0-beta1
                    


                    

                
#r "nuget: TBotPlatform, 2.3.0-beta1"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package TBotPlatform@2.3.0-beta1
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=TBotPlatform&version=2.3.0-beta1&prerelease
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=TBotPlatform&version=2.3.0-beta1&prerelease
                    


                            Install as a Cake Tool

TBotPlatform

NuGet version NuGet downloads License: MIT

A C# library that makes it easy to build Telegram bots.

TBotPlatform is built on top of Telegram.Bot and gives you additional control over your bot: a state machine, update routing, retries, rate limiting, logging, delayed-message queues, caching and distributed locks — capabilities that are hard or impossible to achieve with the raw Bot API.

Highlights

  • State machine — model your bot flow as states activated via attributes ([StateActivator], [StateInlineActivator], [AdminStateActivator], ...).
  • Multi-bot — run several bots in a single host using keyed services.
  • Resilient HTTP pipeline — Polly retries (including Retry-After handling) plus request rate limiting.
  • Caching — FusionCache with Redis or in-memory backends, fail-safe enabled.
  • Delayed messages — schedule messages via a background queue.
  • Distributed locks — built on FusionCache.
  • Result pattern — typed, error-aware results instead of throwing exceptions everywhere.
  • Logging — every Telegram call is traced with an operation id.

Supported Platforms

Multi-targets .NET 8, .NET 9 and .NET 10.

Quick Start

  1. Install the package:

    dotnet add package TBotPlatform

  2. Define a user, states and a menu, then wire everything up:

    builder.Services
    .AddBotPlatform()
        .AddBot(new TBotSetting { BotName = "echo", Token = token })
            .AddTelegramContext()
            .AddStates(Assembly.GetExecutingAssembly())
            .AddReceivingHandler<EchoReceivingHandler>()
            .Build()
        .AddCache()
            .AddMemoryFusionCache()
            .Build()
        .AddFactories(Assembly.GetExecutingAssembly())
        .AddHostedService()
    .Build();

See the samples folder for a complete runnable echo bot.

Concepts

Term Description
State A class that handles a request from a specific user. Selected by a state attribute.
State attribute An attribute that maps a user command to a state.

Interfaces

Interface Description
IState State methods for handling a request.
IStateFactory Helper factory; resolves a state by its attribute.
IStateBindFactory Helper factory; works with bound states.
IStateContextFactory Creates state contexts, invokes IState methods and refreshes the main (bottom) menu.
IMenuButtonFactory Builds the main menu buttons.
IStateContext Telegram API context: sending/editing messages, documents, the main menu, message buttons, photos, etc., with all necessary checks and validations.
IStateContextMinimal Same as IStateContext, but works without a concrete state inside IStateContextFactory.
ITelegramContext Context with queue and logging for Telegram: direct methods to send/edit messages, receive updates, etc.
ITelegramContextLog Log context for ITelegramContext.
IMenuButton Builds the main (bottom) menu buttons.
IStartReceivingHandler Handles incoming Telegram requests.
IKeyInCache A cache item with a key.
IDistributedLockFactory Distributed lock factory, based on FusionCache.
IDelayQueue Queue for sending delayed messages.

State attributes

Attribute Description
StateActivatorBaseAttribute Base attribute holding all state-defining properties.
StateActivatorAttribute For states that define the main (bottom) menu.
StateInlineActivatorAttribute For states that define inline message buttons.
AdminStateActivatorAttribute Admin variant of StateActivatorAttribute.
AdminStateInlineActivatorAttribute Admin variant of StateInlineActivatorAttribute.

DI configuration

services
    .AddBotPlatform()
        .AddBot(telegramSettings)
            .AddTelegramContext()
            .AddStates(executingAssembly)
            .AddReceivingHandler<StartReceivingHandler>()
            .Build()
        .AddCache()
            .AddRedisFusionCache(redisConnectionString)
                .AddHealthTags(tags)
                .AddHealthName(redisHealthName)
            .Build()
        .Build()
        .AddFactories(executingAssembly)
        .AddHostedService()
    .Build();

For webhook mode, set TBotSetting.WebhookUrl (and optionally WebhookSecretToken). The hosted service registers the webhook automatically. In your HTTP endpoint, deserialize the request body to Update and pass it to ITelegramUpdateProcessor.ProcessUpdate.

Examples

Contacts

Telegram

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
2.3.0-beta2 0 9/17/2026
2.3.0-beta1 50 9/16/2026
2.1.2 87 9/2/2026
2.1.2-beta6 125 6/22/2026
2.1.2-beta5 122 3/5/2026
2.1.2-beta4 118 2/25/2026
2.1.2-beta3 123 2/5/2026
2.1.2-beta2 122 1/13/2026
2.1.1 454 11/20/2025
2.1.0 207 10/16/2025
2.0.0 306 9/24/2025

See the release notes on GitHub: https://github.com/BolotnikovPS/TBotPlatform/releases