How uladzislautsimankou/telegram-botkit works
Purpose and entry points
Telegram.BotKit is a .NET 10 library for Telegram bots, built atop the external Telegram.Bot client. It provides DI-driven handler registration, typed parameter binding, and separate middleware pipelines for update types. The runnable reference host starts at Telegram.BotKit.Example/Program.cs; library consumers configure and build a bot through Telegram.BotKit/Hosting/BotBuilder.cs and Telegram.BotKit/Hosting/BotApplication.cs.
Update ingress and hosting
Telegram updates enter through one of two transport modes:
• Long polling: Telegram.BotKit/Hosting/Background/PollingService.cs runs as a hosted background service.
• ASP.NET Core webhook: Telegram.BotKit/Hosting/Webhook/BotController.cs receives updates, with setup managed by Telegram.BotKit/Hosting/Webhook/WebhookStartupService.cs.
Both paths hand updates to the central update handler, normally Telegram.BotKit/DefaultUpdateHandler.cs; applications may supply their own, as demonstrated by Telegram.BotKit.Example/Services/GlobalUpdateHandler.cs.
Update classification and dispatch
DefaultUpdateHandler classifies Telegram update payloads into commands, callbacks, inline queries, or ordinary messages and delegates to dedicated dispatchers:
• Telegram.BotKit/Pipeline/Dispatchers/CommandDispatcher.cs
• Telegram.BotKit/Pipeline/Dispatchers/CallbackDispatcher.cs
• Telegram.BotKit/Pipeline/Dispatchers/InlineQueryDispatcher.cs
• Telegram.BotKit/Pipeline/Dispatchers/MessageDispatcher.cs
Each dispatcher owns a type-specific pipeline and context model, isolating behavior and failure handling by interaction type.
Middleware and routing boundary
Pipelines compose framework defaults with user-registered middleware interfaces under Telegram.BotKit/Abstractions. Command and message pipelines separate routing from execution; callback and inline-query pipelines route directly to invocation. Core stages include command routing/execution (Telegram.BotKit/Pipeline/Middlewares/Commands/CommandRoutingMiddleware.cs, Telegram.BotKit/Pipeline/Middlewares/Commands/CommandExecutionMiddleware.cs), callback routing, inline query routing, and message routing/execution. Default per-pipeline error boundaries convert routing, binding, and handler failures through error-handler middleware.
Handler contracts, discovery, and invocation
Bot behavior is implemented through typed handler interfaces: commands, callbacks, inline queries, and messages in Telegram.BotKit/Abstractions/Commands/ICommandHandler.cs, Telegram.BotKit/Abstractions/Callbacks/ICallbackHandler.cs, and Telegram.BotKit/Abstractions/Messages/IMessageHandler.cs. Routing selects handlers by command/key/query/message eligibility; invokers construct typed calls and invoke handlers:
Telegram.BotKit/Invocation/CommandHandlerInvoker.cs,
Telegram.BotKit/Invocation/CallbackHandlerInvoker.cs, and
Telegram.BotKit/Invocation/InlineQueryHandlerInvoker.cs.
DI registration is centralized in Telegram.BotKit/Extensions/ServiceCollectionExtensions.cs and Telegram.BotKit/Extensions/ServicesRegistrationExtention.cs.
Parsing and strongly typed binding
Raw Telegram text/query payloads cross into application DTOs through parsers and binders. Commands use Telegram.BotKit/Binding/Parsers/CommandParser.cs plus Telegram.BotKit/Binding/Binders/CommandParameterBinder.cs; callbacks and inline queries use their corresponding parser/binder pairs. Attributes in Telegram.BotKit/Attributes/CommandParamAttribute.cs and Telegram.BotKit/Attributes/InlineQyeryParamAttribute.cs describe DTO mapping, while Telegram.BotKit/Binding/Converters/DefaultValueConverter.cs supplies default scalar conversion. Unknown-command handling is assisted by Telegram.BotKit/Helpers/CommandSearcher.cs.
Stateful messages and application extension points
Message contexts can carry conversational state, loaded before message routing by IMessageStateMiddleware and the framework default in Telegram.BotKit/Pipeline/Middlewares/Messages/DefaultMessageStateMiddleware.cs. State persistence itself remains application-owned. The example demonstrates extension points via concrete handlers in Telegram.BotKit.Example/Handlers, custom error/logging middleware in Telegram.BotKit.Example/Middlewares, and application configuration in Telegram.BotKit.Example/appsettings.json.
Main entry points: BotApplication.cs Bot application · CommandDispatcher.cs Type dispatchers · CommandRoutingMiddleware.cs Command routing and execution · CallbackDispatcher.cs Callback and inline routing
Components 19
Hosting
- Bot builder · Consumer-facing bot configuration and construction.
Telegram.BotKit/Hosting/BotBuilder.cs - Bot application
Telegram.BotKit/Hosting/BotApplication.cs - DI registration · Registers framework services and discovered handlers.
Telegram.BotKit/Extensions/ServiceCollectionExtensions.cs - Telegram.Bot client · External Telegram API client.
- Long polling
Telegram.BotKit/Hosting/Background/PollingService.cs - Webhook endpoint
Telegram.BotKit/Hosting/Webhook/BotController.cs - Webhook setup
Telegram.BotKit/Hosting/Webhook/WebhookStartupService.cs
Update pipelines
- Update handler · Classifies each incoming Telegram update.
Telegram.BotKit/DefaultUpdateHandler.cs - Type dispatchers · Separate command, callback, inline-query, and message pipelines.
Telegram.BotKit/Pipeline/Dispatchers/CommandDispatcher.cs - Command routing and execution · Routes commands, then binds and executes handlers.
Telegram.BotKit/Pipeline/Middlewares/Commands/CommandRoutingMiddleware.cs - Callback and inline routing · Route callbacks and inline queries directly to invocation.
Telegram.BotKit/Pipeline/Dispatchers/CallbackDispatcher.cs - Message state and execution · Loads conversational state before message routing and execution.
Telegram.BotKit/Pipeline/Middlewares/Messages/DefaultMessageStateMiddleware.cs - Pipeline error boundaries · Converts routing, binding, and handler failures.
Binding and invocation
- Parsers and typed binders · Parses payloads and maps parameters into DTOs.
Telegram.BotKit/Binding/Parsers/CommandParser.cs - Handler invokers · Constructs typed calls to selected handlers.
Telegram.BotKit/Invocation/CommandHandlerInvoker.cs - Handler contracts · Command, callback, inline-query, and message extension contracts.
Telegram.BotKit/Abstractions/Commands/ICommandHandler.cs
Application extensions
- Reference host · Configures and runs a sample bot.
Telegram.BotKit.Example/Program.cs - Application handlers · Concrete handlers implement application behavior.
Telegram.BotKit.Example/Handlers - Custom update handler · Optional replacement for the framework update handler.
Telegram.BotKit.Example/Services/GlobalUpdateHandler.cs
Connections 28
- Reference host → Bot builder: configures
- Bot builder → Bot application: builds
- Bot builder → DI registration: registers
- DI registration → Handler contracts: discovers and registers
- Bot application → Long polling: hosts
- Bot application → Webhook endpoint: hosts
- Bot application → Webhook setup: starts
- Long polling → Telegram.Bot client: receives updates
- Webhook setup → Telegram.Bot client: configures webhook
- Telegram.Bot client → Webhook endpoint: delivers updates
- Long polling → Update handler: forwards update
- Webhook endpoint → Update handler: forwards update
- Custom update handler → Update handler: may replace
- Update handler → Type dispatchers: classifies and delegates
- Type dispatchers → Command routing and execution: command updates
- Type dispatchers → Callback and inline routing: callback and inline updates
- Type dispatchers → Message state and execution: message updates
- Command routing and execution → Parsers and typed binders: parses and binds
- Callback and inline routing → Parsers and typed binders: parses and binds
- Parsers and typed binders → Handler invokers: typed arguments
- Command routing and execution → Handler invokers: selected handler
- Callback and inline routing → Handler invokers: selected handler
- Message state and execution → Handler contracts: invokes eligible handler
- Handler invokers → Handler contracts: invokes contract
- Handler contracts → Application handlers: implemented by
- Command routing and execution → Pipeline error boundaries: failures handled by
- Callback and inline routing → Pipeline error boundaries: failures handled by
- Message state and execution → Pipeline error boundaries: failures handled by