HomeProjects
Contact
from 2025/4 to Present View on Github
  • C#
  • .NET8
  • NuGet
  • RestApi
  • CICD

TgBotPlay.WebAPI

A package for effortlessly bootstrapping Telegram Bots in .NET WebAPI projects.
Supports both Polling and WebHook workflows with a unified interface and minimal configuration.

Features

  • Easy Setup: Register all bot services with a single extension method for IServiceCollection.
  • Unified Handler Base: Implement your bot logic by inheriting from TgBotPlayUpdateHandlerBase, handling only the events you care about.
  • Flexible Connection Methods: Switch between Polling and WebHook modes by changing an option—no code changes required.
  • Automatic Reflection-based Event Subscription: Only the handler methods you implement are subscribed—no manual registration.
  • WebAPI Integration: Out-of-the-box API endpoints for Telegram WebHook, configurable controller route and name.
  • Health Checks: (If implemented in your project) for bot and webhook status.
  • Customizable Options: Easily customize polling intervals, webhook refresh intervals, endpoint URLs, and security.

Installation

Install the NuGet package:

dotnet add package TgBotPlay.WebAPI

Quick Start

1. Implement Your Bot Logic

Create a class that inherits from TgBotPlayUpdateHandlerBase and override only the update handlers you need:

public class MyBotHandler : TgBotPlayUpdateHandlerBase
{
    public MyBotHandler(ILogger<MyBotHandler> logger) : base(logger) { }

    protected async Task OnMessage(Message message)
    {
        // Handle incoming messages
    }

    protected async Task OnCallbackQuery(CallbackQuery query)
    {
        // Handle callback queries
    }
}

Available handler methods include:

  • OnMessage(Message message)
  • OnEditedMessage(Message message)
  • OnChannelPost(Message message)
  • OnEditedChannelPost(Message message)
  • OnBusinessConnection(BusinessConnection connection)
  • OnBusinessMessage(BusinessMessage message)
  • OnEditedBusinessMessage(BusinessMessage message)
  • OnDeletedBusinessMessages(DeletedBusinessMessages messages)
  • OnMessageReaction(MessageReaction reaction)
  • OnMessageReactionCount(MessageReactionCount reactionCount)
  • OnInlineQuery(InlineQuery query)
  • (and more—see base class for the full list)

2. Register TgBotPlay in your Program.cs or Startup.cs

builder.Services.AddTgBotPlay<MyBotHandler>(options => options
    .WithToken("<telegram bot token>")
    .AsPollingClient()
    // Customize other options as needed
);

WebAPI Routing

TgBotPlay automatically sets up controller endpoints for receiving updates:

  • POST TgBotPlay/{botToken} — Main webhook endpoint for Telegram updates
  • POST TgBotPlay/{botToken}/HookUp — Start webhook service
  • POST TgBotPlay/{botToken}/HookDown — Stop webhook service

The controller route and endpoint name can be customized using WithController(...) in options (Defaults to TgBotPlay).

Switching Between Polling and WebHook

  • Polling: .AsPollingClient()
  • Webhook: .AsWebHookClient("<host name(ex. xyz.com)>", "<optional secret for additional securiry>")

No other code changes are required!

Advanced Configuration

  • WithController(string name, string template) — Customize controller name and route template.
  • WithPollingInterval(double seconds = 5d) — Set polling interval in seconds.
  • WithWebHookRefreshInterval(double minutes = 60d) — Set how often webhook is refreshed.

Health Checks

You can simply add TgBotPlay Health Checks like this in your Program.cs or Startup.cs:

builder.Services.AddHealthChecks()
    .AddTgBotPlayHealth();

How It Works

  • Reflection-based Handler Registration:
    Only the update handler methods you implement in your handler class are registered for Telegram events.
  • WebHook Management:
    WebHook endpoints are exposed via ASP.NET controllers and can be invoked for health and lifecycle management.
  • Automatic Dependency Injection:
    All dependencies are provided via DI; simply inject what you need in your handler or controllers.
  • Proper Scope Management: Proper scopes are created and managed for webhook and polling workflows internally.

Example

Webhook

builder.Services.AddTgBotPlay<MyBotHandler>(options => options
    .WithToken("<telegram bot token>")
    .AsWebHookClient("<host name(ex. xyz.com)>", "<optional secret for additional securiry>")
    .WithController("TgBotPlay", "TgBotPlay/[action]")
    .WithWebHookRefreshInterval(30) //minuets
);

Polling

builder.Services.AddTgBotPlay<MyBotHandler>(options => options
    .WithToken("<telegram bot token>")
    .AsPollingClient()
    .WithPollingInterval(5) //seconds
);

Contribution

  • You can open Issues for any bug report or feature request.
  • You are free to contribute to this project by following these steps:
    1. Fork this Repo.
    2. Create a new branch for your feature/bugfix in your forked Repo.
    3. Commit your changes to the new branch you just made.
    4. Create a pull request from your branch into the main branch of This Repo(https://github.com/IPdotSetAF/EZButton).

Credits