Skip to main content
Telegrator is a next-generation framework for building Telegram bots in C#, inspired by aspect-oriented programming and the mediator pattern. It enables decentralized, easily extensible, and maintainable bot logic without traditional state machines or monolithic handlers.

​
Why Telegrator?

Traditional Telegram bot development often leads to tangled switch/case statements, complex state machines, and tightly coupled code. Telegrator solves these problems with a modern, declarative approach.

Aspect-Oriented Design

Each handler is an independent aspect that can be composed and extended without modifying existing code.

Mediator Pattern

All updates flow through a central mediator that routes them to appropriate handlers based on filters and priorities.

Declarative Filters

Specify handler conditions using intuitive attributes instead of imperative if/else chains.

Built-in State Management

Manage user and chat state without external storage or manual state machines.

​
Quick Example

Here’s a minimal bot that responds to the /start command in private chats: 
using Telegrator;
using Telegrator.Handlers;
using Telegrator.Annotations;
using Telegram.Bot.Types.Enums;

[CommandHandler, CommandAllias("start"), ChatType(ChatType.Private)]
public class StartHandler : CommandHandler
{
    public override async Task<Result> Execute(
        IAbstractHandlerContainer<Message> container, 
        CancellationToken cancellation)
    {
        await Response("Welcome to the bot!", cancellationToken: cancellation);
        return Result.Ok();
    }
}

// Initialize and start the bot
var bot = new TelegratorClient("<YOUR_BOT_TOKEN>");
bot.Handlers.AddHandler<StartHandler>();
bot.StartReceiving();
No switch statements. No state machine boilerplate. Just clean, declarative handlers.

​
Key Features

Handlers are independent “aspects” of your bot that can be added, removed, or modified without affecting other parts of the codebase. Each handler focuses on a single responsibility.
The UpdateRouter acts as a mediator, receiving all Telegram updates and dispatching them to appropriate handlers based on filters, priorities, and execution order.
Use attributes like [CommandAllias("start")], [TextContains("hello")], and [ChatType(ChatType.Private)] to specify when handlers should execute.
Manage numeric, string, and enum states for users and chats without external databases. State is tracked automatically by the framework.
Fine-grained control over handler execution. Limit concurrent handlers globally or per-handler, and await other updates from within a handler.
Create custom filters, state keepers, and aspect processors. The framework provides extension points at every level.
First-class support for .NET Generic Host, making it easy to integrate with ASP.NET Core applications and background services.

​
Next Steps

Installation

Install Telegrator via NuGet and set up your first project

Quickstart

Build your first Telegram bot in minutes

Core Concepts

Understand the architecture and design principles

API Reference

Explore the complete API documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us