WTelegramClient 3.2.1

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

// Install WTelegramClient as a Cake Tool
#tool nuget:?package=WTelegramClient&version=3.2.1                

API Layer NuGet version Build Status Donate

Telegram Client API library written 100% in C# and .NET

This library allows you to connect to Telegram and control a user programmatically (or a bot, but Telegram.Bot is much easier for that). All the Telegram Client APIs (MTProto) are supported so you can do everything the user could do with a full Telegram GUI client.

This ReadMe is a quick but important tutorial to learn the fundamentals about this library. Please read it all.

⚠️ This library requires understanding advanced C# techniques such as asynchronous programming or subclass pattern matching...
If you are a beginner in C#, starting a project based on this library might not be a great idea.

How to use

After installing WTelegramClient through Nuget, your first Console program will be as simple as:

static async Task Main(string[] _)
{
    using var client = new WTelegram.Client();
    var myself = await client.LoginUserIfNeeded();
    Console.WriteLine($"We are logged-in as {myself} (id {myself.id})");
}

When run, this will prompt you interactively for your App api_hash and api_id (that you obtain through Telegram's API development tools page) and try to connect to Telegram servers. Those api hash/id represent your application and one can be used for handling many user accounts.

Then it will attempt to sign-in (login) as a user for which you must enter the phone_number and the verification_code that will be sent to this user (for example through SMS, Email, or another Telegram client app the user is connected to).

If the verification succeeds but the phone number is unknown to Telegram, the user might be prompted to sign-up (register their account by accepting the Terms of Service) and provide their first_name and last_name.
If the account already exists and has enabled two-step verification (2FA) a password might be required.
In some case, Telegram may request that you associate an email with your account for receiving login verification codes, you may skip this step by leaving email empty, otherwise the email address will first receive an email_verification_code.
All these login scenarios are handled automatically within the call to LoginUserIfNeeded.

After login, you now have access to the full range of Telegram Client APIs. All those API methods require using TL; namespace and are called with an underscore instead of a dot in the method name, like this: await client.Method_Name(...)

Saved session

If you run this program again, you will notice that only api_hash is requested, the other prompts are gone and you are automatically logged-on and ready to go.

This is because WTelegramClient saves (typically in the encrypted file bin\WTelegram.session) its state and the authentication keys that were negotiated with Telegram so that you needn't sign-in again every time.

That file path is configurable (session_pathname), and under various circumstances (changing user or server address) you may want to change it or simply delete the existing session file in order to restart the authentification process.

Non-interactive configuration

Your next step will probably be to provide a configuration to the client so that the required elements are not prompted through the Console but answered by your program.

To do this, you need to write a method that will provide the answers, and pass it on the constructor:

static string Config(string what)
{
    switch (what)
    {
        case "api_id": return "YOUR_API_ID";
        case "api_hash": return "YOUR_API_HASH";
        case "phone_number": return "+12025550156";
        case "verification_code": Console.Write("Code: "); return Console.ReadLine();
        case "first_name": return "John";      // if sign-up is required
        case "last_name": return "Doe";        // if sign-up is required
        case "password": return "secret!";     // if user has enabled 2FA
        default: return null;                  // let WTelegramClient decide the default config
    }
}
...
using var client = new WTelegram.Client(Config);

There are other configuration items that are queried to your method but returning null let WTelegramClient choose a default adequate value. Those shown above are the only ones that have no default values and should be provided by your method.

Returning null for verification_code or password will show a prompt for console apps, or an error otherwise (see FAQ #3 for WinForms)
Returning "" for verification_code requests the resending of the code through another system (SMS or Call).

Another simple approach is to pass Environment.GetEnvironmentVariable as the config callback and define the configuration items as environment variables (undefined variables get the default null behavior).

Finally, if you want to redirect the library logs to your logger instead of the Console, you can install a delegate in the WTelegram.Helpers.Log static property. Its int argument is the log severity, compatible with the LogLevel enum.

Alternative simplified configuration & login

Since version 3.0.0, a new approach to login/configuration has been added. Some people might find it easier to deal with:

WTelegram.Client client = new WTelegram.Client(YOUR_API_ID, "YOUR_API_HASH");
await DoLogin("+12025550156"); // initial call with user's phone_number

async Task DoLogin(string loginInfo) // (add this method to your code)
{
   while (client.User == null)
      switch (await client.Login(loginInfo)) // returns which config is needed to continue login
      {
         case "verification_code": Console.Write("Code: "); loginInfo = Console.ReadLine(); break;
         case "name": loginInfo = "John Doe"; break;    // if sign-up is required (first/last_name)
         case "password": loginInfo = "secret!"; break; // if user has enabled 2FA
         default: loginInfo = null; break;
      }
   Console.WriteLine($"We are logged-in as {client.User} (id {client.User.id})");
}

With this method, you can choose in some cases to interrupt the login loop via a return instead of break, and resume it later by calling DoLogin(requestedCode) again once you've obtained the requested code/password/etc... See WinForms example and ASP.NET example

Example of API call

ℹ️ The Telegram API makes extensive usage of base and derived classes, so be ready to use the various C# syntaxes to check/cast base classes into the more useful derived classes (is, as, case DerivedType )

All the Telegram API classes/methods are fully documented through Intellisense: Place your mouse over a class/method name, or start typing the call arguments to see a tooltip displaying their description, the list of derived classes and a web link to the official API page.

The Telegram API object classes are defined in the TL namespace, and the API functions are available as async methods of Client.

Below is an example of calling the messages.getAllChats API function, enumerating the various groups/channels the user is in, and then using client.SendMessageAsync helper function to easily send a message:

using TL;
...
var chats = await client.Messages_GetAllChats();
Console.WriteLine("This user has joined the following:");
foreach (var (id, chat) in chats.chats)
    switch (chat) // example of downcasting to their real classes:
    {
        case Chat basicChat when basicChat.IsActive:
            Console.WriteLine($"{id}:  Basic chat: {basicChat.title}");
            break;
        case Channel group when group.IsGroup:
            Console.WriteLine($"{id}: Group {group.username}: {group.title}");
            break;
        case Channel channel:
            Console.WriteLine($"{id}: Channel {channel.username}: {channel.title}");
            break;
    }
Console.Write("Type a chat ID to send a message: ");
long chatId = long.Parse(Console.ReadLine());
var target = chats.chats[chatId];
Console.WriteLine($"Sending a message in chat {chatId}: {target.Title}");
await client.SendMessageAsync(target, "Hello, World");

➡️ You can find lots of useful code snippets in EXAMPLES and in the Examples subdirectory.
➡️ Check the FAQ if example codes don't compile correctly on your machine, or other troubleshooting.

<a name="terminology"></a>

Terminology in Telegram Client API

In the API, Telegram uses some terms/classnames that can be confusing as they differ from the terms shown to end-users:

  • Channel: A (large or public) chat group (sometimes called supergroup), or a broadcast channel (the broadcast flag differentiate those)
  • Chat: A private basic chat group with less than 200 members (it may be migrated to a supergroup Channel with a new ID when it gets bigger or public, in which case the old Chat will still exist but will be deactivated)
    ⚠️ Most chat groups you see are really of type Channel, not Chat!
  • chats: In plural or general meaning, it means either Chat or Channel (therefore, no private user discussions)
  • Peer: Either a Chat, a Channel or a User
  • Dialog: Status of chat with a Peer (draft, last message, unread count, pinned...). It represents each line from your Telegram chat list.
  • Access Hash: Telegram requires you to provide a specific access_hash for users, channels, and other resources before interacting with them. See FAQ #4 to learn more about it.
  • DC (DataCenter): There are a few datacenters depending on where in the world the user (or an uploaded media file) is from.
  • Session or Authorization: Pairing between a device and a phone number. You can have several active sessions for the same phone number.

Other things to know

The Client class also offers an OnUpdate event that is triggered when Telegram servers sends Updates (like new messages or status), independently of your API requests. See Examples/Program_ListenUpdates.cs

An invalid API request can result in a RpcException being raised, reflecting the error code and status text of the problem.

The other configuration items that you can override include: session_pathname, email, email_verification_code, session_key, server_address, device_model, system_version, app_version, system_lang_code, lang_pack, lang_code, user_id, bot_token

Optional API parameters have a default value of null when unset. Passing null for a required string/array is the same as empty (0-length). Required API parameters/fields can sometimes be set to 0 or null when unused (check API documentation or experiment).

I've added several useful converters, implicit cast or helper properties to various API objects so that they are more easy to manipulate.

Beyond the TL async methods, the Client class offers a few other methods to simplify the sending/receiving of files, medias or messages, as well as generic handling of chats/channels.

This library works best with .NET 5.0+ (faster, no dependencies) and is also available for .NET Standard 2.0 (.NET Framework 4.6.1+ & .NET Core 2.0+) and Xamarin/Mono.Android

Library uses and limitations

This library can be used for any Telegram scenario including:

  • Sequential or parallel automated steps based on API requests/responses
  • Real-time monitoring of incoming Updates/Messages
  • Download/upload of files/media
  • Exchange end-to-end encrypted messages/files in Secret Chats
  • Building a full-featured interactive client

It has been tested in a Console app, in Windows Forms, in ASP.NET webservice, and in Xamarin/Android.

Don't use this library for Spam or Scam. Respect Telegram Terms of Service as well as the API Terms of Service or you might get banned from Telegram servers.

If you read all this ReadMe, the Frequently Asked Questions, the Examples codes and still have questions, feedback is welcome in our Telegram group @WTelegramClient

If you like this library, please consider a donation ❤ This will help the project keep going.

Product Compatible and additional computed target framework versions.
.NET net5.0 is compatible.  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 (5)

Showing the top 5 NuGet packages that depend on WTelegramClient:

Package Downloads
WTelegramClient.Extensions.Updates

Extensions over WtelegramClient For Dealing With Updates

WTelegramBot

Telegram Bot API (local server) library providing more extended features Release Notes: - Bot API 7.6 (https://core.telegram.org/bots/api#july-1-2024): Paid media, Star transactions, more bot business methods, caption-above, effects... - Full compatibility with Telegram.Bot v21.4 ! Migration of code is even simplified as: - We are sharing the same types (Telegram.Bot is now a dependency of the library) - No more MessageEntity specifics - WTelegramBotClient class is compatible with ITelegramBotClient

MTProto

A MTProto client library based on wiz0u/WTelegramClient

WTC.Abstractions.Types

Telegram Type Abstractions For WTelegramClient

WTC.Abstractions.Account

WTelegramClient Abstractions for easier (Multiple) Account handling.

GitHub repositories (2)

Showing the top 2 popular GitHub repositories that depend on WTelegramClient:

Repository Stars
yiyungent/KnifeHub
🧰 简单易用的效率工具平台
DamianMorozov/TgDownloader
Telegram Downloader
Version Downloads Last updated
4.1.5-dev.1 27 7/12/2024
4.1.4 460 7/7/2024
4.1.3 223 7/6/2024
4.1.2 366 7/2/2024
4.1.2-dev.8 53 7/1/2024
4.1.2-dev.7 156 6/15/2024
4.1.2-dev.6 48 6/15/2024
4.1.2-dev.5 130 6/4/2024
4.1.2-dev.4 73 5/28/2024
4.1.2-dev.3 47 5/27/2024
4.1.2-dev.2 154 5/7/2024
4.1.2-dev.1 62 5/1/2024
4.1.1 4,511 4/28/2024
4.1.1-dev.5 50 4/28/2024
4.1.1-dev.2 53 4/27/2024
4.1.1-dev.1 49 4/27/2024
4.0.1 1,004 4/24/2024
4.0.1-dev.6 64 4/22/2024
4.0.1-dev.5 52 4/18/2024
4.0.1-dev.4 42 4/17/2024
4.0.1-dev.3 55 4/16/2024
4.0.1-dev.2 54 4/14/2024
4.0.1-dev.1 59 4/13/2024
4.0.0 2,039 4/5/2024
4.0.0-dev.8 56 4/4/2024
4.0.0-dev.7 48 4/3/2024
4.0.0-dev.6 84 3/30/2024
4.0.0-dev.5 56 3/29/2024
4.0.0-dev.4 63 3/28/2024
4.0.0-dev.2 72 3/26/2024
4.0.0-dev.1 58 3/26/2024
3.7.2 1,322 3/24/2024
3.7.2-dev.3 65 3/23/2024
3.7.2-dev.2 75 3/19/2024
3.7.2-dev.1 72 3/13/2024
3.7.1 3,027 3/8/2024
3.6.7-dev.13 49 3/8/2024
3.6.7-dev.12 50 3/8/2024
3.6.7-dev.11 46 3/8/2024
3.6.7-dev.9 61 3/8/2024
3.6.7-dev.8 65 3/4/2024
3.6.7-dev.7 109 2/25/2024
3.6.7-dev.6 80 2/21/2024
3.6.7-dev.5 61 2/19/2024
3.6.7-dev.4 68 2/18/2024
3.6.7-dev.3 59 2/18/2024
3.6.7-dev.1 49 2/18/2024
3.6.6 2,224 2/1/2024
3.6.5 2,563 1/18/2024
3.6.4 525 1/16/2024
3.6.4-dev.2 60 1/16/2024
3.6.4-dev.1 55 1/15/2024
3.6.3 3,407 12/31/2023
3.6.3-dev.1 73 12/31/2023
3.6.2 1,121 12/23/2023
3.6.2-dev.2 67 12/23/2023
3.6.2-dev.1 92 12/17/2023
3.6.1 2,405 11/30/2023
3.6.1-dev.7 58 11/30/2023
3.6.1-dev.6 63 11/29/2023
3.6.1-dev.2 85 11/25/2023
3.6.1-dev.1 149 11/17/2023
3.5.10-dev.1 96 11/11/2023
3.5.9 2,572 11/6/2023
3.5.8 1,441 10/28/2023
3.5.8-dev.5 68 10/28/2023
3.5.8-dev.4 122 10/24/2023
3.5.8-dev.3 70 10/24/2023
3.5.8-dev.2 101 10/19/2023
3.5.8-dev.1 104 10/9/2023
3.5.7 2,395 10/4/2023
3.5.6 1,347 9/22/2023
3.5.5 1,037 9/18/2023
3.5.5-dev.1 59 9/18/2023
3.5.4 2,742 9/6/2023
3.5.4-dev.2 70 9/6/2023
3.5.3 7,018 7/21/2023
3.5.2-dev.21 77 7/21/2023
3.5.2-dev.20 167 7/7/2023
3.5.2-dev.19 92 7/6/2023
3.5.2-dev.16 78 7/5/2023
3.5.2-dev.15 127 6/27/2023
3.5.2-dev.3 890 5/18/2023
3.5.2-dev.1 74 5/17/2023
3.5.1 20,245 5/17/2023
3.5.1-dev.4 77 5/17/2023
3.5.1-dev.3 467 5/9/2023
3.5.1-dev.2 140 5/5/2023
3.5.1-dev.1 95 5/2/2023
3.4.3-dev.4 82 5/1/2023
3.4.3-dev.3 90 4/29/2023
3.4.3-dev.2 163 4/25/2023
3.4.3-dev.1 105 4/25/2023
3.4.2 4,574 4/24/2023
3.4.2-dev.2 77 4/24/2023
3.4.2-dev.1 92 4/23/2023
3.4.1 1,056 4/21/2023
3.4.1-dev.5 75 4/21/2023
3.4.1-dev.4 156 4/9/2023
3.4.1-dev.2 80 4/8/2023
3.4.1-dev.1 104 4/2/2023
3.3.4-dev.1 91 4/1/2023
3.3.3 2,252 3/26/2023
3.3.3-dev.2 101 3/26/2023
3.3.3-dev.1 148 3/16/2023
3.3.2 1,913 3/9/2023
3.3.2-dev.2 85 3/9/2023
3.3.2-dev.1 88 3/9/2023
3.3.1 910 3/8/2023
3.3.1-dev.1 88 3/8/2023
3.2.3-dev.5 191 2/26/2023
3.2.3-dev.4 134 2/17/2023
3.2.3-dev.3 90 2/15/2023
3.2.3-dev.2 87 2/14/2023
3.2.3-dev.1 89 2/13/2023
3.2.2 7,725 2/6/2023
3.2.2-dev.7 102 2/5/2023
3.2.2-dev.6 109 2/4/2023
3.2.2-dev.5 121 1/26/2023
3.2.2-dev.4 167 1/12/2023
3.2.2-dev.3 119 1/9/2023
3.2.2-dev.2 110 1/7/2023
3.2.2-dev.1 109 1/6/2023
3.2.1 3,570 12/29/2022
3.2.1-dev.2 105 12/29/2022
3.2.1-dev.1 100 12/29/2022
3.1.6-dev.2 130 12/19/2022
3.1.6-dev.1 100 12/15/2022
3.1.5 2,372 12/7/2022
3.1.4-dev.6 92 12/7/2022
3.1.4-dev.5 94 12/5/2022
3.1.4-dev.4 110 12/2/2022
3.1.4-dev.3 115 11/26/2022
3.1.4-dev.2 95 11/26/2022
3.1.4-dev.1 97 11/26/2022
3.1.3 2,030 11/23/2022
3.1.3-dev.5 93 11/23/2022
3.1.3-dev.3 100 11/20/2022
3.1.2 1,727 11/12/2022
3.0.3 1,861 11/1/2022
3.0.2 1,851 10/26/2022
3.0.1 1,275 10/21/2022
3.0.0 3,240 10/8/2022
2.6.4 4,295 9/14/2022
2.6.3 1,794 9/2/2022
2.6.2 4,180 8/6/2022
2.5.2 3,912 7/1/2022
2.5.1 18,357 6/15/2022
2.4.1 22,324 5/20/2022
2.3.3 1,663 5/14/2022
2.3.2 1,966 5/7/2022
2.3.1 3,789 4/13/2022
2.2.1 4,742 3/28/2022
2.1.4 1,297 3/23/2022
2.1.3 1,367 3/18/2022
2.1.2 31,236 2/27/2022
2.1.1 2,973 2/13/2022
2.0.3 1,664 2/7/2022
2.0.2 1,152 2/4/2022
2.0.1 1,554 1/30/2022
2.0.0 1,582 1/24/2022
1.9.4 1,361 1/19/2022
1.9.3 1,173 1/17/2022
1.9.2 3,220 1/11/2022
1.9.1 1,181 1/3/2022
1.8.3 989 12/30/2021
1.8.2 1,668 12/25/2021
1.8.1 1,080 12/21/2021
1.7.6 1,280 12/12/2021
1.7.5 1,226 12/6/2021
1.7.4 1,542 12/1/2021
1.7.3 2,146 11/27/2021
1.7.2 1,524 11/20/2021
1.7.1 986 11/10/2021
1.6.4 1,043 11/6/2021
1.6.3 952 11/3/2021
1.6.2 953 10/31/2021
1.6.1 973 10/31/2021
1.5.1 994 10/25/2021
1.4.1 932 10/20/2021
1.3.1 924 10/19/2021
1.3.0 993 10/17/2021
1.0.2 979 10/15/2021
1.0.1 903 10/11/2021
1.0.0 1,047 9/30/2021
0.9.5 1,021 9/1/2021
0.9.4 924 8/29/2021
0.9.3 907 8/24/2021
0.9.2 915 8/19/2021
0.9.1 963 8/16/2021
0.8.1 962 8/13/2021
0.7.4 958 8/10/2021
0.7.3 913 8/9/2021
0.7.1 1,012 8/8/2021

- API Layer 151: media spoiler flag, personal profile photo, UpdateUser...
- Changed the ordering of optional parameters: Moved bool parameters to the end of parameter list
- Helper simplified method for Channels_GetAdminLog
- Signal wrong use of some params[] methods
- Improved documentation