🚀 TeleFrame

Build Telegram Bots in .NET with the simplicity of Minimal APIs.

TeleFrame is a lightweight Telegram Bot Framework for .NET that brings Dependency Injection, Middleware, Filters, Routing, and State Management to Telegram bot development.

Instead of dealing with large update switch statements and repetitive Telegram Bot API boilerplate, TeleFrame lets you define commands, messages, update handlers, middleware, filters, and conversation states using a clean and familiar developer experience.

bot.MapCommand("/start", () => "Welcome to TeleFrame!");

---

📚 Table of Contents

• 📦 Installation
• 🚀 Quick Start
  • Configuration
  • Create Bot
• 💉 Dependency Injection
• ⌨️ Commands
  • Returning Plain Text
  • Returning a Telegram Response
  • Using UpdateContext
• 💬 Message Handlers
• 🎙️ Voice Messages
• 🔄 Update Handlers
• 🛠️ Middleware
  • Register Middleware
  • Inline Middleware
  • Custom Middleware
• 🛡️ Filters
  • Creating a Filter
  • Applying a Filter
• 🧠 State Management
  • Set State
  • Require State
  • Clear State
• 📌 UpdateContext
• 📨 Results API
• 📋 Logging
• 🎯 Example Application
• 🤔 Why TeleFrame?
• 🗺️ Roadmap
• 🤝 Contributing
• 📄 License

---

Installation

Install the package from NuGet:

dotnet add package TeleFrame

---

Quick Start

Configuration

TeleFrame loads the bot token from the application configuration. By default, the framework looks for a botConfig.json file in the application root.

botConfig.json

Create a botConfig.json file next to your application's executable:

{
  "Token": "YOUR_BOT_TOKEN"
}

Using User Secrets (Recommended for Development)

Instead of storing your bot token inside a configuration file, you can use .NET User Secrets:

dotnet user-secrets init
dotnet user-secrets set "Token" "YOUR_BOT_TOKEN"

TeleFrame automatically loads User Secrets from the entry assembly, allowing you to keep sensitive credentials out of source control.

Configuration Priority

Configuration sources are loaded in the following order:

1. botConfig.json
2. .NET User Secrets

If the same key exists in multiple sources, the value from the last loaded source is used.

Important: Never commit real bot tokens to a public repository. For local development, User Secrets are the recommended approach.

Create a bot in just a few lines:

var builder = new TelegramBotBuilder(args);

var bot = builder.Build();

bot.MapCommand("/start", () => "Welcome to TeleFrame!");

bot.Run();

---

Dependency Injection

TeleFrame integrates with Microsoft's Dependency Injection container.

Register services:

builder.Services.AddScoped<AdminsService>();

Inject them directly into handlers:

bot.MapCommand("/admins", (AdminsService service) =>
{
    return string.Join(", ", service.Admins);
});

No manual service resolution required.

---

Commands

Commands are the most common way to interact with users.

Returning Plain Text

bot.MapCommand("/start", () =>
{
    return "Welcome to TeleFrame!";
});

Returning a Telegram Response

bot.MapCommand("/hi", () =>
{
    return Results.Reply("Hello World");
});

Using UpdateContext

bot.MapCommand("/help", (UpdateContext ctx) =>
{
    var username = ctx.Update.Message!.From!.Username;

    return Results.Reply(
        $"Hello {username}",
        messageEffect: MessageEffects.Heart);
});

---

Message Handlers

Handle specific message types.

bot.MapMessage(MessageType.Text, () =>
{
    return "Text message received";
});

Example:

bot.MapMessage(MessageType.Photo, () =>
{
    return "Nice photo!";
});

---

Voice Messages

Handle voice messages with a dedicated API.

bot.MapVoice(() =>
{
    return Results.Reply("You sent a voice message!");
});

---

Update Handlers

Handle Telegram updates directly.

Example:

bot.MapUpdate(UpdateType.EditedMessage, (UpdateContext ctx) =>
{
    var message = ctx.Update.EditedMessage!;

    return Results.Reply(
        $"You edited: {message.Text}");
});

Example for boost notifications:

bot.MapUpdate(UpdateType.ChatBoost,
    (UpdateContext ctx, AdminsService service) =>
{
    foreach (var admin in service.Admins)
    {
        ctx.Client.SendMessage(
            admin.Id,
            "Channel boosted");
    }
});

---

Middleware

TeleFrame provides a middleware pipeline similar to ASP.NET Core.

Middleware can inspect, modify, or stop processing updates.

Register Middleware

builder.Services.AddScoped<BlackListMiddleware>();

bot.Use<BlackListMiddleware>();

Inline Middleware

bot.Use(next => (context, ct) =>
{
    Console.WriteLine("Update received");

    return next(context, ct);
});

---

Custom Middleware

public class BlackListMiddleware : IUpdateMiddleware
{
    public async Task InvokeAsync(
        UpdateContext context,
        UpdateDelegate next,
        CancellationToken ct)
    {
        var blocked = false;

        if (blocked)
            return;

        await next(context, ct);
    }
}

---

Filters

Filters allow validation and authorization before executing handlers.

Creating a Filter

public class OnlyAdminsFilter
    : IUpdateHandlerFilter
{
    public Task InvokeAsync(
        UpdateContext context,
        UpdateHandlerFilterDelegate next,
        CancellationToken ct)
    {
        var isAdmin = true;

        if (isAdmin)
            return next(context, ct);

        return Task.CompletedTask;
    }
}

Applying a Filter

bot.MapCommand("/admins", () =>
{
    return "Admin panel";
})
.Filter<OnlyAdminsFilter>();

---

State Management

TeleFrame includes a simple conversation state system.

Perfect for multi-step user interactions.

---

Set State

bot.MapCommand("/verify",
    (IStateManager stateManager) =>
{
    stateManager.SetState(
        "awaiting_phone_number");

    return "Please enter your phone number.";
});

---

Require State

bot.MapMessage(MessageType.Text,
    (UpdateContext ctx,
     IStateManager stateManager) =>
{
    var input = ctx.Update.Message!.Text!;

    stateManager.ClearState();

    return "Verification complete.";
})
.RequireState("awaiting_phone_number");

---

Clear State

stateManager.ClearState();

---

UpdateContext

UpdateContext gives you access to:

• Telegram Client
• Current Update
• User Information
• Chat Information
• Services
• State Management
• Request Context

Example:

bot.MapCommand("/me", (UpdateContext ctx) =>
{
    var user = ctx.Update.Message!.From!;

    return Results.Reply(
        $"Hello {user.FirstName}");
});

---

Results API

Return rich responses using the Results helper.

Results.Reply("Hello");

Results.Reply(
    "Welcome!",
    messageEffect: MessageEffects.Heart);

---

Logging

Enable update logging with a single line.

Register:

builder.Services.AddUpdateLogging();

Use:

bot.UseUpdateLogging();

---

Example Application

var builder = new TelegramBotBuilder(args);

builder.Services.AddScoped<AdminsService>();

var bot = builder.Build();

bot.MapCommand("/start",
    () => "Welcome to TeleFrame!");

bot.MapVoice(
    () => "Voice message received!");

bot.MapCommand("/verify",
    (IStateManager stateManager) =>
{
    stateManager.SetState("awaiting_phone");

    return "Enter your phone number.";
});

bot.Run();

---

Why TeleFrame?

Telegram bot development often starts simple but quickly becomes difficult to maintain as your bot grows.

TeleFrame solves this by bringing proven ASP.NET Core concepts to Telegram bots:

• Routing
• Middleware
• Dependency Injection
• Filters
• State Management
• Clean Architecture Friendly

You focus on business logic.

TeleFrame handles the plumbing.

---

Roadmap

• Callback Query Routing
• Inline Query Support
• Webhook Hosting
• Background Jobs
• Localization Support
• Built-in Authorization

---

Contributing

Contributions, ideas, bug reports, and pull requests are welcome.

If you find TeleFrame useful, consider giving the repository a ⭐.

---

License

Licensed under the MIT License.