Volgor.TelegramService 1.1.0

TelegramBotClient

TelegramBotClient is a library (multi-targeting .NET Standard 2.1 and .NET 8) designed to facilitate interaction with the Telegram Bot API. It provides methods for sending messages and files to individual chats or multiple chats simultaneously. It was developed specifically for Volgor Cloud.

Table of Contents

1. Features
2. Installation
3. Usage
4. Dependency Injection
5. Result Model
6. Handling Resources
7. References

Features

• Send Messages: Send text messages to a single chat or broadcast to multiple chats.
• Send Files: Share documents with a single chat or multiple recipients.
• Result Handling: Each operation returns a Result object indicating success or failure, along with error details if applicable.
• Cheap, non-blocking construction: Creating a client performs no network I/O, so it is safe to register as a singleton. Connections are pooled across the process and a flaky IPv6 path cannot stall requests (connect timeout + Happy Eyeballs dual-stack racing).

Upgrading from 1.0.0: the constructor used to call Telegram's getMe synchronously and could throw TaskCanceledException — which crashed the host when a client was created from a background timer. As of 1.1.0 the constructor never touches the network. If you relied on construction failing for an invalid token, call ValidateAsync instead.

Installation

You can install the package via NuGet:

dotnet add package Volgor.TelegramService --version 1.1.0

Usage

1. Initialize the Client:

Create an instance of TelegramBotClient by providing your bot token (no network call is made):

TelegramBotClient botClient = new TelegramBotClient("your_bot_token");

1.5. (Optional) Validate the token:

Result validation = await botClient.ValidateAsync();
if (!validation.IsSuccess)
{
    Console.WriteLine($"Bot token invalid or Telegram unreachable: {validation.ErrorMessage}");
}

2. Send a Message:

2.1. To a Single Chat:

var result = await botClient.SendMessageAsync("chat_id", "Hello, World!");
if (result.IsSuccess)
{
    Console.WriteLine("Message sent successfully.");
}
else
{
    Console.WriteLine($"Failed to send message: {result.ErrorMessage}");
}

2.2. To Multiple Chats:

var chatIds = new List<string> { "chat_id_1", "chat_id_2" };
var result = await botClient.SendMessageAsync(chatIds, "Hello, everyone!");

3. Send a File:

3.1. To a Single Chat:

byte[] fileContent = File.ReadAllBytes("path_to_file");
var result = await botClient.SendFileAsync("chat_id", fileContent, "file_name.pdf", "Here is your document.");

3.2. To Multiple Chats:

var chatIds = new List<string> { "chat_id_1", "chat_id_2" };
byte[] fileContent = File.ReadAllBytes("path_to_file");
var result = await botClient.SendFileAsync(chatIds, fileContent, "file_name.pdf", "Here is the document for everyone.");

4. Result Handling:

Each operation returns a Result object indicating success or failure. You can check the IsSuccess property to determine the outcome of the operation:

if (result.IsSuccess)
{
    Console.WriteLine("Operation was successful.");
}
else
{
    Console.WriteLine($"Operation failed: {result.ErrorMessage}");
}

Dependency Injection

Because construction is cheap and thread-safe, register the client as a singleton and reuse it:

builder.Services.AddSingleton(_ =>
    new TelegramBotClient(builder.Configuration.GetSection("TelegramSettings")["BotToken"]));

Do not register it as scoped/transient and resolve it inside a Timer/IHostedService callback per tick — that recreates the client constantly and was the source of the old crash loop. A single shared instance pools its connections internally.

For full control over the underlying HttpClient (e.g. with IHttpClientFactory), use the secondary constructor:

builder.Services.AddHttpClient<TelegramBotClient>()
    .AddTypedClient((http, sp) =>
        new TelegramBotClient(sp.GetRequiredService<IConfiguration>().GetSection("TelegramSettings")["BotToken"], http));

Result Model

The Result model contains the following properties:

public class Result
{
    public bool IsSuccess { get; }
    public string ErrorMessage { get; }

    public Result(bool isSuccess, string errorMessage = null)
    {
        IsSuccess = isSuccess;
        ErrorMessage = errorMessage;
    }
}

Handling Resources

Ensure to dispose of the TelegramBotClient instance to free up resources:

botClient.Dispose();

References

• Telegram Bot API