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 6.2 released on August 12, 2022.
- Contains pre-defined methods for all Bot API 6.2 methods.
- Contains classes for each object type used in the Bot API 6.2.
- Sync and async methods.
- Support System.Text.Json and Newtonsoft.Json.
- NET Standard >= 2.0
- NET Core >= 2.0, NET 5 and NET 6
- NET Framework >= 4.6.2
- Universal Windows Platform >= 10.0.16299
- Unity >= 2018.1
$ dotnet add PROJECT package Telegram.BotAPI
Get package from Nuget Web Site
First, get your bot token from BotFather and use it to create a new instance of Telegram.BotAPI.BotClient
as follows.
using Telegram.BotAPI;
var botToken = "bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11";
// You need a BotClient instance if you want access to the Bot API methods.
var api = new BotClient(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 BotClient 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 = api.GetMe();
Console.WriteLine("My name is {0}.", me.FirstName);
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.
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 = api.GetUpdates();
while (true)
{
if (updates.Any())
{
foreach (var update in updates)
{
// Process update
}
var offset = updates.Last().UpdateId + 1;
updates = api.GetUpdates(offset);
}
else
{
updates = api.GetUpdates();
}
}
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([FromBody] Update update)
{
if (update == null)
{
return BadRequest();
}
// 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 use a secret path to access the api controller.
Using webhook will disable the
getUpdates
method. UsedeleteWebhook
to enable it again.
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.
You can send attached files using InputFile objects. You have two ways to do it.
using Telegram.BotAPI;
using Telegram.BotAPI.AvailableTypes;
using Telegram.BotAPI.AvailableMethods;
var file = new InputFile(filebytes, "file.zip");
// Upload document
api.SendDocument(chatId, file);
using Telegram.BotAPI;
using Telegram.BotAPI.AvailableTypes;
using Telegram.BotAPI.AvailableMethods;
var file = new InputFile(filebytes, "file.zip");
var files = new AttachedFile[]
{
new AttachedFile("file56", file)
}
// Upload document
api.SendDocument(chatId, "attach://file56", attachedFiles: files);
You can see more examples here.
If you wish, you can donate through the following methods:
- Bitcoin: bc1q0w43tprjn80zn248k7xlztu7lvhkzgy6dak8mt
- Toncoin: EQC3SWZxs_4ive2aD-njns1KnB4S2RUgaxDKJ7X44VA52SsY