WTelegramClient 1.6.1

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

How to use

⚠️ This library relies on asynchronous C# programming (async/await) so make sure you are familiar with this before proceeding.

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 user = await client.LoginUserIfNeeded();
    Console.WriteLine($"We are logged-in as {user.username ?? user.first_name + " " + user.last_name} (id {user.id})");
}

When run, this will prompt you interactively for your App api_id and api_hash (that you obtain through Telegram's API development tools page) and try to connect to Telegram servers.

Then it will attempt to sign-in 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 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 (accepting the Terms of Service) and enter their first_name and last_name.

And that's it, you now have access to the full range of Telegram services, mainly through calls to await client.Some_TL_Method(...)

Saved session

If you run this program again, you will notice that only api_id and api_hash are 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 negociated with Telegram so that you needn't sign-in again every time.

That file path is configurable, 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 (in bold above) 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 <u>should be provided</u> by your method. Returning null for verification_code or password will show a prompt for console apps, or an error otherwise.

Another simpler 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 classic LogLevel enum

Example of API call

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

To find which derived classes are available for a given base class, the fastest is to check our TL.Schema.cs source file as they are listed in groups. Intellisense tooltips on API structures/methods will also display a web link to the adequate Telegram documentation 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 and 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(null);
Console.WriteLine("This user has joined the following:");
foreach (var (id, chat) in chats.chats)
    switch (chat)
    {
        case Chat smallgroup when (smallgroup.flags & Chat.Flags.deactivated) == 0:
            Console.WriteLine($"{id}:  Small group: {smallgroup.title} with {smallgroup.participants_count} members");
            break;
        case Channel channel when (channel.flags & Channel.Flags.broadcast) != 0:
            Console.WriteLine($"{id}: Channel {channel.username}: {channel.title}");
            break;
        case Channel group:
            Console.WriteLine($"{id}: Group {group.username}: {group.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");

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) chat group (sometimes called supergroup) or a broadcast channel (the broadcast flag differenciate those)
• Chat : A private simple chat group with few people (it may be migrated to a supergroup/channel when it doesn't fit anymore)
• Chats : In plural, it means either Chat or Channel
• Peer : Either a Chat, Channel or a private chat with a User
• Dialog : The current status of a chat with a Peer (draft, last message, unread count, pinned...)
• DC (DataCenter) : There are a few datacenters depending on where in the world the user (or an uploaded media file) is from.
• Access Hash : For more security, Telegram requires you to provide the specific access_hash for chats, files and other resources before interacting with them (not required for a simple Chat). This is like showing a pass that proves you are entitled to access it. You obtain this hash when you first gain access to a resource and occasionnally later when some events about this resource are happening or if you query the API. You should remember this hash if you want to access that resource later.

Other things to know

The Client class also offers an Update event that is triggered when Telegram servers sends unsollicited Updates or notifications/information/status/service messages, 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.

You can find more code examples in EXAMPLES.md and in the Examples subdirectory.

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

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 object 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.

This library works best with .NET 5.0+ and is also available for .NET Standard 2.0 (.NET Framework 4.6.1+ & .NET Core 2.0+)

Troubleshooting guide

Here is a list of common issues and how to fix them so that your program work correctly:

1. Are you using the Nuget package or the library source code? <br/>It is not recommended to copy/compile the source code of the library for a normal usage. <br/>When built in DEBUG mode, the source code connects to Telegram test servers. So you can either:

   • Recommended: Use the official Nuget package or the private nuget feed of development builds
   • Build your code in RELEASE mode
   • Modify your config callback to reply to "server_address" with the IP address of Telegram production servers (as found on your API development tools)

2. After ConnectAsync(), are you calling LoginUserIfNeeded()? <br/>If you don't authenticate as a user (or bot), you have access to a very limited subset of Telegram APIs

3. Did you use await with every Client methods? <br/>This library is completely Task-based and you should learn, understand and use the asynchronous model of C# programming before proceeding further.

4. Are you keeping a live reference to the Client instance and dispose it only at the end of your program? <br/>If you create the instance in a submethod and don't store it somewhere permanent, it might be destroyed by the garbage collector at some point. So as long as the client must be running, make sure the reference is stored in a (static) field or somewhere appropriate. <br/>Also, as the Client class inherits IDisposable, remember to call client.Dispose() when your program ends (or exit a using scope).

5. Is your program ending immediately instead of waiting for Updates? <br/>Your program must be running/waiting continuously in order for the background Task to receive and process the Updates. So make sure your main program doesn't end immediately. For a console program, this is typical done by waiting for a key or some close event.

6. Is every Telegram API call rejected? (typically with an exception message like AUTH_RESTART) <br/>The user authentification might have failed at some point (or the user revoked the authorization). It is therefore necessary to go through the authentification again. This can be done by deleting the WTelegram.session file, or at runtime by calling client.Reset()

Library uses and limitations

This library can be used for any Telegram scenarios including:

• Sequential or parallel automated steps based on API requests/responses
• Real-time monitoring of incoming Updates/Messages
• Download/upload of files/media
• etc...

Secret chats (end-to-end encryption, PFS) and connection to CDN DCs have not been tested yet.

Developers feedbacks are welcome in the Telegram channel @WTelegramClient

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