Forem: Ali Salehi

Update handling in WTelegramClient

Ali Salehi — Tue, 09 Jan 2024 10:15:35 +0000

in the previous article we talked about starting to work with WTC and setting up the basic requirements. in this article we are going through the process of handling updates for beginners. lets get started.

setup

we have our basic hello world code from previous article here:

using var client = new WTelegram.Client(Config);

await client.LoginUserIfNeeded();
return;

static string? Config(string what)
{
    switch (what)
    {
        case "session_pathname":  return Path.Join(Environment.CurrentDirectory, "mysessionFILE.session");
        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;
    }
}

Github

don't forget to replace your phone number, your api_id & api_hash and also your 2FA password.

subscribing to updates

the first thing we need to do, is to tell the WTC that we want to listen to the incoming updates, to do that we simply subscribe to an Event called OnUpdate:

client.OnUpdate += UpdateHandler;
async Task UpdateHandler(UpdatesBase updatesBase) {
    return;
}

lets talk about what just happened here, first we have our client which at this point "might" be logged-in, we don't know yet, when we are subscribing (+=) to an Event which gives us an object of type UpdatesBase and needs us to return a Task, basically a Func<UpdatesBase, Task> (we'll talk about that in the future) and then we are returning right after the subscription.

if your code is not async you can do return Task.CompletedTask; and remove the async.

Updates

Telegram Type system by many people is considered Complex, or Confusing, and maybe it is, you just have to work with it for a relatively long time (that literally the definition of complexity but whatever). but I believe it would be much much more complex IF we didn't have pattern-matching in C#, BUT WE DO!

lets look at the basic types in WTC.
first we have something called UpdatesBase, It derives from IObject. an empty interface, this is due to serialization reasons, but you don't need to worry about this, you just need know this:

every Telegram object inside the WTC, drives from IObject.

lets look at its fields:

Update[] UpdateList;
Dictionary<long, User> Users;
Dictionary<long, ChatBase> Chats;
DateTime Date;

we are going to talk about the most important one: UpdateList,
as the name says, this is an list of Update.

all the updates that we need are going to be inside this array.
if you receive one message, this is going to be an array with one item inside it, if you get 10 messages in a very short period of time, lets say in 200 milli seconds, this array is going to be filled with 10 items.

but if you are getting 1 message every seconds, your UpdateHandler will be called 10 times with 1 message each time.

so it is important to check the whole array of update and not just the first or last item.
so we'll write:

async Task UpdateHandler(UpdatesBase updatesBase)
{
    foreach (Update? update in updatesBase.UpdateList)
    {

    }
}

take a closer look, the update variable is an Update?. what is it?

public abstract class Update : IObject { }

this is very similar to the concept of IObject, as you can see its an abstract class that has no items inside it, just like the IObject, this is the base definition of every Update inside the WTC.
remember that I said:
every object is an IObject.
but also every update drives from Update, for the same reasons!

so what should we do with it ? this is where the pattern-matching comes into play, we can cast this object to whatever we think it might be!

you can hover over this type in your IDE and see that types it CAN be, for example:

this is what it looks like in my IDE, tons of types! but don't let it scare you, we don't need all of them! in fact we only need a few!

reading the updates

alright lets start with something simple, we want to see all the new text messages!

we can do the following:

foreach (Update? update in updatesBase.UpdateList)
{
    if (update is UpdateNewMessage newMessage)
    {
    }
}

in this code, we are Safe casting the update to the type UpdateNewMessage which is responsible for the incoming & outgoing new messages inside a (basic) group or private chat.
with the if statement we indicate that if the update is not what we wanted, do not PANIC, don't throw any exceptions, just relax and continue to the next update, if we did something like this:

foreach (Update? update in updatesBase.UpdateList)
{
    var newMsg = (UpdateNewMessage)update;
}

it would cause some problems, since we are hard casting here, compiler would assume that it is 100% the given type, so it wont check for anything first, but we are not 100% sure that the update is UpdateNewMessage, are we? it could be one of those many types that we saw earlier, so it will throw error and potentially break our application.
so its much cleaner and safer to do the pattern matching with the if statement ( or even switch-statements if you have multiple types to handle).

lets see what we have inside the newMessage:

MessageBase message;
int pts;
int pts_count;

ignore the pts stuff here

we are seeing a new type: MessageBase, you are going to see a lot of ..Base types while working with Telegram API, (average OOP moment 😂)
but this one is not completely useless to us, it contains some information about the message, the 2 important ones are:

Peer Peer;
DateTime Date;

the Peer is itself another long discussion but for now, lets say its a Person for the sake of simplicity, this Peer only has one field: ID of the person(a unique identifier).
and the date is the time when the message was sent.

so we can print them:

if (update is UpdateNewMessage newMessage)
{
    var fromId = newMessage.message.Peer.ID;
    Console.WriteLine($"msg from {fromId} at {newMessage.message.Date}");
}

you will see something like this in the console:

msg from 5298595170 at 1/7/2024 6:56:44 AM

so we got the data and the sender id, but where the heck is the text?

not that fast, there is another type

the newMessage.message can be one of these 3 things:

MessageEmpty
Message
MessageService

for now, we will be using Message, so we can write:

if (update is UpdateNewMessage newMessage)
{
    var fromId = newMessage.message.Peer.ID;
    Console.WriteLine($"msg from {fromId} at {newMessage.message.Date}");
    if (newMessage.message is Message msg)
    {

    }
}

so now the msg contains the information we need, but first lets make this code a bit clear and more readable, we can return early when the update is something that we don't need:

if (update is not UpdateNewMessage newMessage) 
    continue;

var fromId = newMessage.message.Peer.ID;
Console.Write($"msg from {fromId} at {newMessage.message.Date}");

if (newMessage.message is not Message msg) 
    continue;

Console.WriteLine($" text: {msg.message}");

using the not operator we indicate that if the update is not what we wanted, just continue iterating over the list, and the same thing for the newMessage.message and then finally we can print out all the text messages!

msg from 1548097770 at 1/7/2024 8:44:50 AM text: HELLO WTC!

The alternative

now that you've learned the update handling in the hard way, let me introduce you to the easy way:

there is an extension package called WTelegramClient.Extensions.Updates, go ahead and install it:

> dotnet add package WTelegramClient.Extensions.Updates

using this package you can simply do this:

client.RegisterUpdateType<UpdateNewMessage>(async (message, updateBase) =>
{
    Console.WriteLine($"msg from {message.message.Peer.ID}");
});

//or..

client.RegisterUpdateType<UpdateNewMessage>(OnNewMessage);

async Task OnNewMessage(UpdateNewMessage message, UpdatesBase? updateBase)
{
    Console.WriteLine($"msg from {message.message.Peer.ID}");
}

so you can basically filter any Update type that you want, there are other filters for Chat types and more features, I recommend check it out:

WTelegramClient.Extensions.Updates

different types of content

so far we've learned how to print out the text messages, but there are other things to capture (e.x Documents, Photos, Videos..etc).
we'll cover a few of them in the following section.

Photos

first we want to put all the new pictures inside a Directory, lets call it photos, so we should create it first:

//beginning
var photoDirectory = Path.Combine(Environment.CurrentDirectory, "photos");
if (!Directory.Exists(photoDirectory))
    Directory.CreateDirectory(photoDirectory);

// ..login
//..update handler

simply check if the directory doesn't exist, create it!

now we can look for the photos in our UpdateHandler:

if (newMessage.message is not Message msg)
    continue;

if (msg.media is MessageMediaPhoto messageMediaPhoto)
{

}

okay so the msg.media is a MessageMedia which is just another Base class, this one can be a lot of things as well. but now we only want the photos so we casted it to MessageMediaPhoto.

the messageMediaPhoto has a field called photo which is yet another Base class.
the photo field can be 2 things:

PhotoEmpty
Photo

the first one is completely useless, in almost all the cases you want the Photo, so instead of nesting if statements we can write it like this:

if (msg.media is MessageMediaPhoto {photo: Photo thePicture}) { }

we are simply checking if the type is MessageMediaPhoto AND its photo field is of type Photo in a single if-statement
and finally we are accessing it through the thePicture variable.
keep in mind that if the msg.media is not the specified type, the {photo: Photo thePicture} part is not going to be executed, so you wont be able to use thePicture.

this is equivalent to this code:

if (msg.media is MessageMediaPhoto messageMediaPhoto)
{
    if (messageMediaPhoto.photo is Photo photo) { }
}

we are just checking the 2 conditions at the same level, you can also write it like this:

if (msg.media is MessageMediaPhoto messageMediaPhoto
    && messageMediaPhoto.photo is Photo photo) {}

thePicture has everything you need to know about a picture, lets download it in our desired Directory.

if (msg.media is MessageMediaPhoto {photo: Photo thePicture})
{
    var path = Path.Combine(photoDirectory, $"{thePicture.id}.jpg");
    await using var fs = new FileStream(path, FileMode.OpenOrCreate);
    await client.DownloadFileAsync(thePicture, fs);
}

not much to explain here, we are creating a path using the photo id (you can name it whatever you want) and we are creating a FileStream using that path and using the DownloadFileAsync helper method we are downloading it.
you can test this and go to the ../bin/Debug/net/photos and see the photos you've downloaded!

Documents

in telegram terms, documents are basically any type of media except photo. so videos, GIFs, audio, voice, stickers ...etc.

so process is very similar to downloading photos, first create the directory:

var docDirectory = Path.Combine(Environment.CurrentDirectory, "documents");
if (!Directory.Exists(docDirectory))
    Directory.CreateDirectory(docDirectory);

then check for the document type:

if (is photo...)
{
//..
}
else if (msg.media is MessageMediaDocument { document: Document doc }) //either Document or DocumentEmpty, same as PhotoBase
{
    var filename = doc.Filename ?? $"{doc.id}.{doc.mime_type.Split('/')[1]}";
    var path = Path.Combine(docDirectory, filename);
    await using var fs = new FileStream(path, FileMode.OpenOrCreate);
    await client.DownloadFileAsync(doc, fs);
}

so what we did here is a bit different, for the file name we can check if the FileName has a value (??) if so, we don't need to check for its type, if it doesn't have any name, we split the mime_type by /

mime types are represented like this Video/mp4 or Photo/jpg ..etc

and then we get the second index of the Split so that we can only get the type and with that we create a file name, then make a FileStream and download the file. exactly the same as Photo, you can also go ahead and store the different types in separate directories based on this mime_type but we are not going to do that here.

Blocking

you we've made it, we handled our updates, lets run the application;

what happened? why did the problem aborted immediately? well because we don't block our thread.
after registering our handler:

client.OnUpdate += UpdateHandler;

there is basically no logic to tell the program: "wait until we tell you to exit" or something like that.
how can we fix it?

the most simplest solution could be this:

client.OnUpdate += UpdateHandler;
while (true)
    await Task.Delay(TimeSpan.FromSeconds(1));

yes, put an infinite loop after registering the handler and just sleep for some amount of seconds, doesn't matter you can put TimeSpan.FromDays(99999), just the enough amount to not put any pressure on the CPU.

but this is not a perfect solution!

for a long term running or a production grade application I personally would recommend something like a Background Service (which we are going to cover in the next articles).
for testing, I think anything that works, is fine.

Conclusion

so we managed to handle basic updates that are coming into our account, we didn't do much, but we did the hard part, after this its going to be much more easier.
if you did not find what you were looking for here, you might want to take a look at these links:

if you still didn't find it, don't worry, leave a comment and tell us what could be the topic of the next article!

all the code written in this article is available here.

Introduction to C# User Bots with WTelegramClient

Ali Salehi — Sun, 17 Dec 2023 19:30:16 +0000

In the dynamic landscape of bot development, Telegram stands out as a popular platform, offering a rich(and sometimes confusing) set of APIs for creating fascinating User Bots. If you're venturing into Telegram API development using C#, the WTelegramClient(AKA WTC) library is a powerful tool that deserves your attention.

Different Types of Bots In Telegram

before we continue, lets talk about Different bots in Telegram Ecosystem, what the heck is "User Bot" or "Client Bot" or "API" Bot ? what's the difference?

First One

Telegram allows you to create bots (daaah?) that runs on the cloud and can receives and send content;

some popular examples of these bots are BotFather or ChatId Bot which is used to get the users numerical IDS and many other bots.

these bots are known as "API bots" or "Telegram Bots" mainly because they have a separate and dedicated API that is much simpler and easier to work with, which is not the topic of this article. BUT there is also another type of Bot.

Second One

the second types are the one that can log-in to your account via your phone number, these bots are known as "User Bots" / "Client Bots" or in some cases "Self Bot" because, well they are basically what the Official Client Applications use on Android Or other platforms, that's right, Your Telegram App in your Phone is using "Client API" to interact with Telegram, which is what we are going to talk about in this article.

So what `WTelegramClient` can do ? what roles it plays?

well, It can do anything! you can create Both User Bots and API Bots. But it is mainly used to create user bots; and That's what we are going to do now!

WTC handles all the low-level details of Communications between Telegram and your C# code and gives you a nice and Right amount of abstractions to work with, what I mean by "Right Amount"? well, it's not something like other libraries(e.g: telethon which is a great tool BTW ) that abstract most of the details and exposes a little bit of information.

well isn't that a good thing? you might say

yes and no, too much abstraction "can" take away the flexibility, at least this is what I saw in my experience. The WTelegramClient library only abstract the painful part of The Code and lets you do whatever you want to do with the rest! you can build basically a fully functional Client Application that can do 100% of the official client features. with less pain indeed.

alright enough with the talking and theory BS, Lets Write some Code!

Creating A `Hello world` application in WTC

1. Install The Library

first of all add the WTC (nuget) to your dependencies:

$ dotnet add package WTelegramClient

great! now that you installed the library its time to gather some information.

2.required properties

in order to write Telegram User Bots, unlike regular "Bot APIs" you need 2 unique things besides your phone number:

API Hash
API ID

what are these? well we are not going into detail but these are used to Identify who is sending the request to telegram and who created the application in the first place.
to fetch these you can easily go to the Telegram Site, Enter your phone number, enter the code and after that you see 3 options:

API development tools
Delete account
Log out

click Delete Account and .. no Just Kidding, click the First one which will redirect you to this url then you can create a application with whatever name you want and WALLA!, you got your Api_id and api_hash

now that we have these things we can continue writing our code.

3. writing the Basic

first we need to provide our information to WTC, so we create a function called Config:

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
    }
}

this function accepts a string and also returns a string, its like a Dictionary<String, String>, we are just mapping the WTC requirements to their proper values, so here you can put your ApiHash, ApiId, Phone and your 2FA password.

and now we can create our first instance of WTC:

using var client = new WTelegram.Client(Config);

simple as that! notice that we are not doing Client(Config()); but rather we are passing the Function itself and not its returning value! that's really important because WTC will automatically determine which piece of data it needs!
also don't forget the using at the beginning, otherwise you might face some issues related to resources not getting released!

alright, we have a client now, what can we do with it ? nothing...yet.
if you run the code now, nothing will happen, why? because you didn't login!

4.login

logging in to telegram is simple as writing a single line of code:

await client.LoginUserIfNeeded();

notice that you also have a client.LoginBotIfNeeded() which is used for creating "API bots", cool!.
now if we run the code you should see something similar to this in the console:

WTelegramClient {version} running under .NET {version}
Connecting to {IP of the DC}
4>Sending   InvokeWithLayer`1                        #D8BE
4>Receiving RpcResult                                2023-12-14 14:18:19Z
             → Config                                #D8BE
Connected to DC 4... default_p2p_contacts, revoke_pm_inbox

....
             → Auth_SentCode                         #AE32
A verification code has been sent via App
Code:

now its the time to enter the code that telegram sent to your account, note that you "can't" create new accounts with unofficial clients, this means you have to create your account with an official client first and then use the "Client API", unfortunately!

after entering the code, if you have a 2FA password enabled, you should see something like this:

→ RpcError 401 SESSION_PASSWORD_NEEDED  #66D1
→ Account_Password                      #878D

Verifying encryption key safety... (this should happen only once per DC)
This account has enabled 2FA. A password is needed.

now if you wrote the correct password in the Config function, you should be able to login successfully and see the client disposing without errors:

4>Disposing the client
4>Sending   MsgsAck                                  2023-12-14  (svc)

Process finished with exit code 0.

BUT if you entered the wrong password you will get:

→ RpcError 400 PASSWORD_HASH_INVALID    #B05E
Wrong password!

don't worry, just check your password and run the program again!

5.the session

before we move on, lets talk a little bit about sessions, what are they? well go to the bin directory in your project, next to the Debug/Release directories, you see a file named WTelegram.session which if you logged in successfully you should see it and its size should be more than 0 Bytes.

this is there WTC stores everything related to your state, Authentication and some other details.

some libraries store information about messages, chats, access_hashes (which we will discuss later) ..etc. WTC does NOT store these information and its up to the users of this library to handle them

using this file, you can login once and the next time resume the existing session instead of login.
now go ahead and run your program one more time:

Loaded previous session
WTelegramClient {version} running under .NET {version}
Connecting to {DC IP}
....
4>Disposing the client
Process finished with exit code 0.

notice the first line :Loaded previous session, you are using the pre-stored data to connect to the telegram, without entering the code again, that why our login method is called client.LoginUserIfNeeded() and not client.LoginUser(), we only login if we don't have a valid session file present in the default session path.

changing the default session path

you can also change this path, for example I want the session to be next to my application.exe file, we need to add one more line to the Config function:

// create the path

static string Config(string what)
{
    switch (what)
    {
        // the new "parameter"
        case "session_pathname": return Path.Combine(Environment.CurrentDirectory, "mysessionFILE.session");
        // other stuff
        default: return null;
    }
}

now if you run the program again, you should see that it doesn't say Loaded previous session and its asking for a code, because we moved the session to a new place.
after this if we run it one more time, it reads the mysessionFILE.session and does not ask for the code again! pretty cool.

if you are facing any issue related to the session not being parsed or corruption, just try to delete the session file and login again!

6. HELLO WORLD, finally

now that we are familiar with sessions, lets just print hello world!

//login stuff
//...

await client.SendMessageAsync(InputPeer.Self, "hello WTC world!");

now run the program and take a look at your saved messages inside the official client, can you see the "hello WTC world!" ? you should.

Conclusion

well congratulations! you finally made it! welcome to the world of Telegram Client Development where you will suffer every single second trying to understand the telegram documentations and figure out how to do things! but don't worry, we will help you:

Examples of different methods

WTC Telegram Chat

WTC Documentations

Github Page

Telegram Documentations

All Telegram Method

all the code written in this article are available here.