Endfix.Telegram.BotAPI 0.3.0

Telegram Bot API (С#)

Typed .NET client for the Telegram Bot API. The library targets .NET Standard 2.0 and uses System.Text.Json for request and response contracts.

Features

• strongly typed Bot API methods, parameters and response models;
• polymorphic JSON serialization for Telegram union types;
• JSON and multipart/form-data requests;
• local file uploads, Telegram file IDs and attach:// references;
• sequential or parallel long polling and an ASP.NET Core webhook example;
• contract, transport and live Telegram integration tests;
• BenchmarkDotNet suites and million-request stress profiles.

Installation

dotnet add package Endfix.Telegram.BotAPI --version 0.3.0

Quick start

Each bot is given a unique authentication token when it is created. Store the token in User Secrets or an environment variable; do not put it in appsettings.json or source control. You can learn about obtaining tokens and generating new ones in this document.

var api = new BotApiClient(
    "<token>",
    new HttpClient(new SocketsHttpHandler
    {
        PooledConnectionLifetime = TimeSpan.FromSeconds(5),
        MaxConnectionsPerServer = 10
    })
    {
        Timeout = TimeSpan.FromMinutes(5)
    }
);

var message = await api.SendMessageAsync(
    chatId: 1234567890,
    text: "Hello from Endfix.Telegram.BotAPI");

Examples

• Long polling: sequential (FIFO) or parallel update processing.
• Webhook: ASP.NET Core endpoint with secret-token validation.

Both examples accept TELEGRAM_BOT_TOKEN from an environment variable or .NET User Secrets while retaining their existing appsettings.json keys as a fallback:

dotnet user-secrets set "TELEGRAM_BOT_TOKEN" "<token>" --project Telegram.BotAPI.Examples/LongPolling/Telegram.BotAPI.Example.LongPolling.csproj
dotnet user-secrets set "TELEGRAM_BOT_TOKEN" "<token>" --project Telegram.BotAPI.Examples/Webhook/Telegram.BotAPI.Example.Webhook.csproj

Long polling processes updates sequentially in FIFO order by default (maxParallel = 1). Set maxParallel to a value greater than 1 to enable concurrent processing. FIFO ordering is not guaranteed in parallel mode, including the order in which handlers start or complete. Use sequential processing for stateful workflows that depend on update ordering.

All OnUpdate subscribers are invoked in registration order and each returned task is awaited before processing for that update completes. A failing subscriber is logged without preventing later subscribers from running.

StartPollingAsync uses best-effort, at-most-once delivery semantics. Handler failures do not trigger automatic redelivery: an update is acknowledged when the next getUpdates request advances the offset, and no checkpoint is persisted by the client. Applications that require durable processing or at-least-once delivery should own the GetUpdatesAsync loop and persist their checkpoint explicitly.

The example projects include placeholder configuration files. Replace the placeholders locally or use User Secrets before running them.

Retry behavior

The client automatically retries Telegram responses with error code 429, waiting for the server-provided retry_after interval before the next attempt. It makes at most six retries by default; configure maxRetryAttempts in the constructor or set it to 0 to disable automatic retries. Timeouts, cancellations and other transport failures are not retried automatically because the client cannot know whether Telegram processed the original request.

RequestAsync returns Telegram API responses, while ExecuteAsync throws ApiRequestException when Telegram returns ok = false. Argument errors, caller cancellation, timeouts, HTTP and network failures, and malformed JSON responses retain their standard .NET exception types.

Downloading files

Use this method to get basic information about a file and prepare it for downloading. For the moment, bots can download files of up to 20MB in size.

var message = await api.SendDocumentAsync(
    chatId: 1234567890,
    document: new InputDocumentFile("report.pdf"));

var file = await api.GetFileAsync(message.Document!.FileId);
var fileBytes = await api.GetFileBytesAsync(file.FilePath!);

await File.WriteAllBytesAsync("downloaded-report.pdf", fileBytes);

Tests

Run the solution test suite (live integration tests are skipped when their secrets are not configured):

dotnet test Telegram.BotAPI.sln

Telegram integration tests are disabled unless their credentials are configured. They can send real messages and are intended for a dedicated test bot and chat.

Run local tests without contacting Telegram:

dotnet test Telegram.BotAPI.Tests/Telegram.BotAPI.Tests.csproj --filter "Category!=Integration"

See the test project guide for the live test topology, BotFather settings, administrator rights, secrets, rollback behavior and focused run commands.

Benchmarks

The benchmark project contains serialization, rich-message and local transport benchmarks, plus sequential and bounded-parallel stress profiles:

dotnet run --project Telegram.BotAPI.Benchmarks/Telegram.BotAPI.Benchmarks.csproj -c Release
dotnet run --project Telegram.BotAPI.Benchmarks/Telegram.BotAPI.Benchmarks.csproj -c Release -- --stress
dotnet run --project Telegram.BotAPI.Benchmarks/Telegram.BotAPI.Benchmarks.csproj -c Release -- --stress-parallel 10

Status

The project follows the Telegram Bot API release it targets. While the package remains below 1.0, public contracts may still change to correct modeling issues or complete the file-source API. After 1.0, incompatible public API changes will require a major version.

Releases

Push the intended release commit to main and wait for CI to pass before creating a vX.Y.Z tag. Pushing the tag starts the publish workflow, which independently restores, builds, tests, packs with the version derived from the tag, and publishes the package to NuGet.

License

This project is licensed under the MIT License.