Telegram.BotAPI
7.2.0
See the version list below for details.
dotnet add package Telegram.BotAPI --version 7.2.0
NuGet\Install-Package Telegram.BotAPI -Version 7.2.0
<PackageReference Include="Telegram.BotAPI" Version="7.2.0" />
paket add Telegram.BotAPI --version 7.2.0
#r "nuget: Telegram.BotAPI, 7.2.0"
// Install Telegram.BotAPI as a Cake Addin #addin nuget:?package=Telegram.BotAPI&version=7.2.0 // Install Telegram.BotAPI as a Cake Tool #tool nuget:?package=Telegram.BotAPI&version=7.2.0
Telegram.BotAPI
Telegram.BotAPI is one of the most complete libraries available to interact with the Telegram Bot API in your .NET projects. Free and open source.
It contains all the methods and types available in the Bot API 7.2 released on March 31, 2024.
Features
- Contains pre-defined methods for all Bot API 7.2 methods.
- Contains classes for each object type used in the Bot API 7.2.
- Sync and async methods.
- Uses System.Text.Json by default.
How to use
First, get your bot token from BotFather and use it to create a new instance of Telegram.BotAPI.TelegramBotClient
as follows.
using Telegram.BotAPI;
var botToken = "bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11";
// You need a TelegramBotClient instance if you want access to the Bot API methods.
var client = new TelegramBotClient(botToken);
The methods and types are organized in namespaces according to their corresponding section on the Official Bot API website. So if you want to use a method or type, you must first include the corresponding namespace.
Currently the following namespaces are available:
Name | Description |
---|---|
Telegram.BotAPI | Contains the TelegramBotClient and other utilities |
Telegram.BotAPI.GettingUpdates | Contains methods and types for getting updates |
Telegram.BotAPI.AvailableTypes | Contains available types |
Telegram.BotAPI.AvailableMethods | Contains available methods |
Telegram.BotAPI.UpdatingMessages | Contains methods and types for updating messages |
Telegram.BotAPI.Stickers | Contains methods and types for stickers |
Telegram.BotAPI.InlineMode | Contains methods and types for inline mode |
Telegram.BotAPI.Payments | Contains methods and types for payments |
Telegram.BotAPI.TelegramPassport | Contains methods and types for Telegram Passport |
Telegram.BotAPI.Games | Contains methods and types for games |
Once the namespaces are included, you are ready to start managing your bot. For example, you can use the getMe method to get basic information about your bot.
using Telegram.BotAPI.AvailableMethods;
var me = client.GetMe();
Console.WriteLine("My name is {0}.", me.FirstName);
Getting updates
Every time a user interacts with a bot, bot will receive a new update. Updates contain information about user events, such as a new message or when a button is clicked. If you want your bot to reply to a message, then your bot must be able to get updates first.
Currently, there are two ways to get updates: Long Polling and webhooks.
Long Polling
To get updates using Long Polling, you must create a perpetual loop and check for updates using the getUpdates method. After all updates have been processed, you must mark them as read by setting the offset parameter to a value greater than the id of the last update. See the follow example:
using System.Linq;
using Telegram.BotAPI.GettingUpdates;
var updates = client.GetUpdates();
while (true)
{
if (updates.Any())
{
foreach (var update in updates)
{
// Process update
}
var offset = updates.Last().UpdateId + 1;
updates = client.GetUpdates(offset);
}
else
{
updates = client.GetUpdates();
}
}
Webhooks
To receive updates through webhook, you must create a web application. In your ASP NET application, create a new api controller for your bot and define a function to receive the update as shown below.
using Telegram.BotAPI.GettingUpdates;
[HttpPost]
public IActionResult Post(
// The secret token is optional, but it's highly recommended to use it.
[FromHeader(Name = "X-Telegram-Bot-Api-Secret-Token")] string secretToken,
[FromBody] Update update)
{
if (update is null)
{
return BadRequest();
}
// Check if the secret token is valid
// Process your update
return Ok();
}
At the beginning of your application, you need to register your webhook using the API. In this way, Telegram will send new updates to your API controller. See the example below:
api.DeleteWebhook(true); // Delete old webhook
api.SetWebhook("https://example.com/<controller path>"); // Set new webhook
It's high recommended to configurate a secret token to access the api controller through the setWebhook method. This will prevent third parties from accessing your api controller. Using a webhook will disable the
getUpdates
method. UsedeleteWebhook
to enable it again.
Sending messages
Sending messages is the simplest and most important task of a bot. See the following example for sending text messages.
using Telegram.BotAPI.AvailableMethods;
long chatId = update.Message.Chat.Id; // Target chat Id
api.SendMessage(chatId, "Hello World!"); // Send a message
Your bot can also send multimedia messages like photos, gifs, videos, and others. See Available methods for learn more.
Uploading files
You can also send attached files using InputFile objects. You have two ways to do it: By using an InputFile object directly or by using an AttachedFile object.
Option 1
using Telegram.BotAPI;
using Telegram.BotAPI.AvailableTypes;
using Telegram.BotAPI.AvailableMethods;
var file = new InputFile(filebytes, "file.zip");
// Upload document
api.SendDocument(chatId, file);
Option 2
using Telegram.BotAPI;
using Telegram.BotAPI.AvailableTypes;
using Telegram.BotAPI.AvailableMethods;
var file = new InputFile(filebytes, "file.zip");
var files = new Dictionary<string, InputFile>() {
{ "file56", file }
};
// Upload document
api.SendDocument(chatId, "attach://file56", files: files);
Making custom requests
The library already includes all types and methods available in the Bot API. However, if you want to use your own types or if you want to be the first one to use new features when they are released, you can use the CallMethod
and/or CallMethodDirect
methods defined in the ITelegramBotClient instance.
var args = new Dictionary<string, object>() {
{ "chat_id", 123456789 },
{ "text", "Hello World!" }
};
// Message is the type you want to use to deserialize the response result. It can be an in-built type or a custom type created by you.
var message = client.CallMethod<Message>("sendMessage", args);
The previous method is used by all extension methods defined in the library. You can also create your own extension methods to make custom requests if you want.
public static class TelegramBotClientExtensions
{
public static Message SendHelloWorld(this ITelegramBotClient client, long chatId)
{
var args = new Dictionary<string, object>() {
{ "chat_id", chatId },
{ "text", "Hello World!" }
};
return client.CallMethod<Message>("sendMessage", args);
}
}
The library also includes the classes MethodNames
and PropertyNames
that contain the names of all methods and properties.
The CallMethod
will trigger an exception if the response status code is not OK. If you don't like this behavior, you can use the CallMethodDirect
method instead.
var args = new Dictionary<string, object>() {
{ "chat_id", 123456789 },
{ "text", "Hello World!" }
};
// BotResponse<Message>
var response = client.CallMethodDirect<Message>("sendMessage", args);
You'll get a BotResponse<T>
object as a response. This object contains the status code, the deserialized result or null (if error), the error description and also some error parameters if available.
Examples
You can see more examples here.
License
Release notes
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. 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 was computed. 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 was computed. 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. |
.NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
.NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen40 was computed. tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- System.Text.Json (>= 8.0.3)
NuGet packages (3)
Showing the top 3 NuGet packages that depend on Telegram.BotAPI:
Package | Downloads |
---|---|
Telegram.BotAPI.Extensions
Package Description |
|
Nutil.Tools.TelegramBot
Nutil.Tools.TelegramBot是Nutil应用框架Telegram的应用层类库 |
|
Burtimax.TelegramBot.MultipleBotFramework
Framework для Telegram ботов. Пакет, который помогает создавать Telegram ботов быстро и качественно. Для правильного использования пакета смотри руководство README.md в репозитории (https://github.com/burtimax/BotTemplateWebApi). |
GitHub repositories (1)
Showing the top 1 popular GitHub repositories that depend on Telegram.BotAPI:
Repository | Stars |
---|---|
Eptagone/Telegram.BotAPI
Telegram Bot API NET. One of the most complete libraries available to interact with the Telegram Bot API.
|
Version | Downloads | Last updated | |
---|---|---|---|
7.10.0 | 830 | 9/7/2024 | |
7.9.0 | 957 | 8/15/2024 | |
7.7.0 | 1,656 | 7/7/2024 | |
7.6.0 | 253 | 7/2/2024 | |
7.5.0 | 2,001 | 6/18/2024 | |
7.4.0 | 888 | 5/29/2024 | |
7.3.1 | 654 | 5/14/2024 | |
7.3.0 | 1,070 | 5/7/2024 | |
7.2.1 | 146 | 5/6/2024 | |
7.2.0 | 1,266 | 3/31/2024 | |
7.1.1 | 4,034 | 2/24/2024 | |
6.9.2 | 4,789 | 10/21/2023 | |
6.9.0 | 791 | 9/24/2023 | |
6.8.0 | 2,127 | 8/27/2023 | |
6.7.2 | 2,901 | 6/5/2023 | |
6.7.1 | 1,910 | 4/22/2023 | |
6.6.1 | 1,156 | 4/8/2023 | |
6.6.0 | 1,142 | 3/13/2023 | |
6.5.1 | 4,941 | 2/22/2023 | |
6.4.0 | 1,184 | 1/2/2023 | |
6.3.1 | 399 | 12/27/2022 | |
6.3.0 | 1,775 | 11/7/2022 | |
6.2.0 | 3,057 | 8/14/2022 |
- Updated to Bot API 7.2