Zentix.TelegramToolkit 0.1.0

Zentix.TelegramToolkit

A reusable .NET library for building services on top of WTelegram.Client.

It centralizes Telegram client lifecycle, session persistence, update routing, and DI registration so application projects do not have to re-implement these concerns.

What It Provides

• ITelegramClientProvider for resolving configured/managed WTelegram.Client instances.
• ITelegramSessionService for checking and deleting sessions by stable session key.
• File-based session store.
• Client lifecycle management (in-memory client cache + reconnect/restore behavior).
• Filtered update routing abstractions and implementation.
• One-line DI setup: AddZentixTelegramToolkit(...).

Build And Test

Use the repo solution:

dotnet restore Zentix.TelegramToolkit.slnx
dotnet build Zentix.TelegramToolkit.slnx -c Release --no-restore
dotnet test Zentix.TelegramToolkit.slnx -c Release --no-build

Package And Publish

Tag-based publishing is automated via the GitHub Actions workflow at .github/workflows/publish-package.yml.

• Create a tag in the format vX.Y.Z (example: v1.0.0).
• Push the tag to GitHub.
• The workflow builds, tests, packs, and publishes to NuGet.org using the NUGET_API_KEY repository secret.

Local pack command:

dotnet pack src/Zentix.TelegramToolkit.csproj -c Release -p:Version=1.0.0 -o artifacts

Install

The package is published to NuGet.org:

dotnet add package Zentix.TelegramToolkit

DI Setup

using Zentix.TelegramToolkit.Hosting;

builder.Services.AddZentixTelegramToolkit(builder.Configuration);

Configuration

Required runtime config

{
  "TelegramClient": {
    "ApiId": 123456,
    "ApiHash": "your_api_hash",
    "SessionsFolderPath": "./data/sessions"
  }
}

Optional named accounts config

Use when you want account-key based lookup without passing phone per call:

{
  "TelegramClient": {
    "ApiId": 123456,
    "ApiHash": "your_api_hash",
    "SessionsFolderPath": "./data/sessions",
    "Accounts": {
      "main": {
        "PhoneNumber": "+10000000000"
      }
    }
  }
}

The account dictionary key is your stable session key. It can be any alias (including the phone number itself if you choose), but session identity is derived from that key, not from PhoneNumber.

The session file name is the provided session key under SessionsFolderPath (for example: ./data/sessions/main). Invalid filename characters are replaced with _.

Core Usage

Get Telegram client

using Zentix.TelegramToolkit.Hosting;

var client = await telegramClientProvider.GetClientAsync("main", cancellationToken);

For user-driven auth/session flows (dynamic phone), use overload with phone:

var client = await telegramClientProvider.GetClientAsync(
    sessionKey: userId.ToString(),
    phoneNumber: phoneNumber,
    cancellationToken: cancellationToken);

Session checks

using Zentix.TelegramToolkit.Sessions;

var status = await telegramSessionService.CheckAsync("main", cancellationToken);
if (status.State == TelegramSessionState.ValidSession)
{
    // ready
}

await telegramSessionService.DeleteAsync("main", cancellationToken);

For dynamic flows without named account config:

var status = await telegramSessionService.CheckAsync(
    sessionKey: userId.ToString(),
    phoneNumber: phoneNumber,
    cancellationToken: cancellationToken);

Public API Surface

Key namespaces:

• Zentix.TelegramToolkit.Hosting
• Zentix.TelegramToolkit.Sessions
• Zentix.TelegramToolkit.Configuration
• Zentix.TelegramToolkit.Abstractions

Notes

• The toolkit is infrastructure-focused and does not contain app/business logic.
• The public surface is intentionally small; internal types under Integration/ are implementation detail and may change between minor versions.