TelegramNotifier 2.0.0

.NET 6.0

dotnet add package TelegramNotifier --version 2.0.0

NuGet\Install-Package TelegramNotifier -Version 2.0.0

This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.

<PackageReference Include="TelegramNotifier" Version="2.0.0" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

<PackageVersion Include="TelegramNotifier" Version="2.0.0" />
                    

                            Directory.Packages.props

<PackageReference Include="TelegramNotifier" />
                    

                            Project file

For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.

paket add TelegramNotifier --version 2.0.0

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: TelegramNotifier, 2.0.0"

#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.

#:package TelegramNotifier@2.0.0

#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.

#addin nuget:?package=TelegramNotifier&version=2.0.0
                    

                            Install as a Cake Addin

#tool nuget:?package=TelegramNotifier&version=2.0.0
                    

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

TelegramNotifier

A lightweight .NET library for sending logs and exceptions to Telegram with support for queuing, retries, and background processing.

Key Features

Sending messages to Telegram with log level prefixes
Automatic exception reporting via middleware
Long messages sent as .txt file attachments (> 2000 chars)
Support for Telegram forum topics (MessageThreadId)
Asynchronous queue processing (Channel + BackgroundService)
Resilient delivery: exponential backoff + rate-limit handling
Exception type filtering
Duplicate throttling — suppresses repeated exceptions within a time window
App name and environment included in notifications automatically
Custom exception formatter

Supported Platforms

.NET 6
.NET 7
.NET 8
.NET 9

Installation

dotnet add package TelegramNotifier

See CHANGELOG.md for version history.

Registration

Three ways to register — pick the one that fits your setup.

1. From code only

builder.Services.AddTelegramNotifier(options =>
{
    options.BotToken = "YOUR_BOT_TOKEN";
    options.ChatId = "-100XXXXXXXXXX";
    options.Enabled = true;
});

2. From `appsettings.json`

{
  "TelegramNotifier": {
    "Enabled": true,
    "BotToken": "YOUR_BOT_TOKEN",
    "ChatId": "-100XXXXXXXXXX",
    "MessageThreadId": 6
  }
}

builder.Services.AddTelegramNotifier(
    builder.Configuration.GetSection("TelegramNotifier"));

3. From `appsettings.json` + override from code

builder.Services.AddTelegramNotifier(
    builder.Configuration.GetSection("TelegramNotifier"),
    options =>
    {
        options.DuplicateThrottleWindow = TimeSpan.FromMinutes(5);
        options.ExcludedExceptionTypes.Add(typeof(OperationCanceledException));
    });

Configuration options

Parameter	Type	Default	Description
`BotToken`	`string`	—	Telegram bot token
`ChatId`	`string`	—	Target chat or group ID
`Enabled`	`bool`	`true`	Master switch — set to `false` to silence all sending
`MessageThreadId`	`int?`	`null`	Topic ID for forum groups
`MaxRetryCount`	`int`	`3`	Max retry attempts on HTTP failure
`ApplicationName`	`string?`	auto	App name shown in notifications (auto-filled from host)
`EnvironmentName`	`string?`	auto	Environment shown in notifications (auto-filled from host)
`DuplicateThrottleWindow`	`TimeSpan`	`Zero`	Suppress duplicate exception types within this window
`ExcludedExceptionTypes`	`ICollection<Type>`	`[]`	Exception types (and subclasses) to never send
`ExceptionFormatter`	`Func<Exception, HttpContext?, string>?`	`null`	Custom formatter for exception body

Middleware — automatic exception reporting

Add to capture all unhandled exceptions automatically:

app.UseTelegramNotifier();

Usage

Send a message with log level

await _notifier.SendMessageAsync("Server started");                              // 🟢 [INFO]
await _notifier.SendMessageAsync("Queue is 80% full", LogLevel.Warning);         // 🟡 [WARN]
await _notifier.SendMessageAsync("Database unavailable", LogLevel.Error);        // 🔴 [ERROR]
await _notifier.SendMessageAsync("Service crashed", LogLevel.Critical);          // 🚨 [CRIT]

Send an exception manually

try
{
    // ...
}
catch (Exception ex)
{
    await _notifier.SendExceptionAsync(ex);
}

Inject into a controller

public class OrdersController : ControllerBase
{
    private readonly ITelegramNotifier _notifier;

    public OrdersController(ITelegramNotifier notifier)
    {
        _notifier = notifier;
    }

    [HttpPost]
    public async Task<IActionResult> Create(OrderDto dto)
    {
        await _notifier.SendMessageAsync($"New order: {dto.Id}", LogLevel.Information);
        return Ok();
    }
}

Exception filtering

Suppress specific exception types (including subclasses):

options.ExcludedExceptionTypes.Add(typeof(OperationCanceledException));
options.ExcludedExceptionTypes.Add(typeof(BadHttpRequestException));

Duplicate throttling

Prevent the same exception type from flooding Telegram:

options.DuplicateThrottleWindow = TimeSpan.FromMinutes(5);

One notification per exception type per 5 minutes.

Custom exception formatter

Override the default exception body format:

options.ExceptionFormatter = (ex, ctx) =>
    $"Error: {ex.Message}\nPath: {ctx?.Request.Path}\nTime: {DateTime.UtcNow}";

If the result exceeds 2000 characters it is sent as a .txt file — the caption stays auto-generated.

Security

Never store BotToken in source code
Use appsettings.json, environment variables, or a secrets manager

How to get ChatId

Private chat with the bot

Send any message to your bot
Open: https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates
Find "chat": { "id": 123456789 } — that is your ChatId

Group

Add the bot to the group and send a message
Open the same getUpdates URL
Find "chat": { "id": -1001234567890 } — group IDs are negative

Forum group (topics)

ChatId — the group ID
MessageThreadId — the topic ID (visible in the URL when you open a topic)

If getUpdates returns nothing, make sure no webhook is set: https://api.telegram.org/bot<YOUR_BOT_TOKEN>/deleteWebhook

Product	Compatible and additional computed target framework versions.
.NET	net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 is compatible. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 is compatible. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 was computed. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed.

Product

.NET

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

net6.0
- Microsoft.AspNetCore.Http.Abstractions (>= 2.2.0)
- Microsoft.Extensions.Hosting (>= 6.0.0)
- Microsoft.Extensions.Http (>= 6.0.0)
- Microsoft.Extensions.Options.ConfigurationExtensions (>= 6.0.0)
net7.0
- Microsoft.AspNetCore.Http.Abstractions (>= 2.2.0)
- Microsoft.Extensions.Hosting (>= 6.0.0)
- Microsoft.Extensions.Http (>= 6.0.0)
- Microsoft.Extensions.Options.ConfigurationExtensions (>= 6.0.0)
net8.0
- Microsoft.AspNetCore.Http.Abstractions (>= 2.2.0)
- Microsoft.Extensions.Hosting (>= 6.0.0)
- Microsoft.Extensions.Http (>= 6.0.0)
- Microsoft.Extensions.Options.ConfigurationExtensions (>= 6.0.0)
net9.0
- Microsoft.AspNetCore.Http.Abstractions (>= 2.2.0)
- Microsoft.Extensions.Hosting (>= 6.0.0)
- Microsoft.Extensions.Http (>= 6.0.0)
- Microsoft.Extensions.Options.ConfigurationExtensions (>= 6.0.0)

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version	Downloads	Last Updated
2.0.0	121	6/4/2026
1.0.1	165	4/16/2026
1.0.0	126	4/16/2026

See full changelog: https://github.com/bekov0004/TelegramNotifier/blob/main/CHANGELOG.md