Telegram.BotAPI 6.3.0

There is a newer version of this package available.
See the version list below for details.
dotnet add package Telegram.BotAPI --version 6.3.0                
NuGet\Install-Package Telegram.BotAPI -Version 6.3.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="Telegram.BotAPI" Version="6.3.0" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Telegram.BotAPI --version 6.3.0                
#r "nuget: Telegram.BotAPI, 6.3.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.
// Install Telegram.BotAPI as a Cake Addin
#addin nuget:?package=Telegram.BotAPI&version=6.3.0

// Install Telegram.BotAPI as a Cake Tool
#tool nuget:?package=Telegram.BotAPI&version=6.3.0                

Telegram.BotAPI

Compatible with Bot API v6.3

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.3 released on November 5, 2022.


Features

  • Contains pre-defined methods for all Bot API 6.3 methods.
  • Contains classes for each object type used in the Bot API 6.3.
  • Sync and async methods.
  • Support System.Text.Json and Newtonsoft.Json.

How to use

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);

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 = 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();
    }
}

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([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. Use deleteWebhook 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 send attached files using InputFile objects. You have two ways to do it.

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 AttachedFile[]
{
    new AttachedFile("file56", file)
}
// Upload document
api.SendDocument(chatId, "attach://file56", attachedFiles: files);

Examples

You can see more examples here.

License

MIT

Release notes

See release notes

Product 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

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 711 9/7/2024
7.9.0 914 8/15/2024
7.7.0 1,621 7/7/2024
7.6.0 251 7/2/2024
7.5.0 1,900 6/18/2024
7.4.0 881 5/29/2024
7.3.1 637 5/14/2024
7.3.0 1,051 5/7/2024
7.2.1 146 5/6/2024
7.2.0 1,238 3/31/2024
7.1.1 3,989 2/24/2024
6.9.2 4,746 10/21/2023
6.9.0 791 9/24/2023
6.8.0 2,109 8/27/2023
6.7.2 2,897 6/5/2023
6.7.1 1,900 4/22/2023
6.6.1 1,156 4/8/2023
6.6.0 1,139 3/13/2023 6.6.0 is deprecated because it has critical bugs.
6.5.1 4,827 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 6.3