Telethon/README.md

Telethon

Telethon is Telegram client implementation in Python. This project's core is completely based on TLSharp. All the files which are fully based on it will have a notice on the top of the file. Also don't forget to have a look to the original project.

The files without the previously mentioned notice are no longer part of TLSharp itself, or have enough modifications to make them entirely different.

Table of contents

• Why Telethon?
• Requirements
  • Python modules
  • Obtaining your API ID and Hash
• Running Telethon
• Advanced uses
  • How to add more functions to TelegramClient
  • Tips for porting Telethon
  • Code generator limitations
• Plans for the future

Why Telethon?

Why should I bother with Telethon? You already mentioned TLSharp. telegram-cli has also been around for a long while. And we have the official clients!

With Telethon you don't really need to know anything before using it. Create a client with your settings. Connect. You're ready to go.

Being written on Python, Telethon can run as a script under any environment you wish, (yes, Android too). You can schedule it, or use it in any other script you have. Want to send a message to someone when you're available? Write a script. Do you want check for new messages at a given time and find relevant ones? Write a script.

An official client has a feature which Telethon doesn't? Implement it easily.

Requirements

Python modules

This project requires the following Python modules, which can be installed by issuing sudo -H pip3 install <module> on a Linux terminal:

• pyaes (GitHub, package index)

Obtaining your API ID and Hash

1. Follow this link and login with your phone number.
2. Click under API Development tools.
3. A Create new application window will appear. Fill in your application details. There is no need to enter any URL, and only the first two fields (App title and Short name) can be changed later as long as I'm aware.
4. Click on Create application at the end. Now that you have the API ID and Hash, head to api/ directory and create a copy of the settings_example file, naming it settings (lowercase!). Then fill the file with the corresponding values (your api_id, api_hash and phone number in international format).

Running Telethon

First of all, you need to run the tl_generator.py by issuing python3 tl_generator.py. This will generate all the TLObjects from the given scheme.tl file. When it's done, you can run python3 main.py to start the interactive example.

Advanced uses

How to add more functions to TelegramClient

As of now, you cannot call any Telegram function unless you first write it by hand under tl/telegram_client.py. Why? Every Telegram function (or Request) work in its own way. In some, you may only be interested in a single result field, and in others you may need to format the result in a different way. However, a plan for the future is to be able to call any function by giving its namespace.name and passing the arguments. But until that happens, to add a new function do:

1. Have a look under tl/functions/ and find the Request that suits your needs.
2. Have a look inside that Request you chose, and find what arguments and in what order you'll need to call it.
3. Import it in tl/telegram_client.py by using from tl.functions import SomeTelegramRequest.
4. Add a new method, or function, that looks as follows:

def my_function(self, my_arguments):
    request = SomeTelegramRequest(my_arguments)

    self.sender.send(request)
    self.sender.receive(request)
    
    return request.result

To determine how the result will look like, simply look at the original .tl definition. After the =, you will see the type. Let's see an example: stickerPack#12b299d4 emoticon:string documents:Vector<long> = StickerPack;

As it turns out, the result is going to be an StickerPack. Without a second doubt, head into tl/types/ and find it; open the file and see what the result will look like. Alternatively, you can simply print(str(request.result))!

Be warned that there may be more than one different type on the results. This is due to Telegram's polymorphism, for example, a message may or not be empty, etc.

Hint: You could even write your own class based on TelegramClient and add more features.

Tips for porting Telethon

First of all, you need to understand how the scheme.tl (TL language) works. Every object definition is written as follows:

name#id argument_name:argument_type = CommonType

This means that in a single line you know what the TLObject name is. You know it's unique ID, and you know what arguments it has. It really isn't that hard to write a generator for generating code to any platform!

The generated code should also be able to encode the Request into bytes, so they can be sent over the network. This isn't a big deal either, because you know how the TLObject's are made.

Once you have your own code generator, start by looking at the first release of Telethon. The code there is simple to understand, easy to read and hence easy to port. No extra useless features. Only the bare bones. Perfect for starting a new implementation.

P.S.: I may have lied a bit. The TL language is not that easy. But it's not that hard either. You're free to sniff the parser/ files and learn how to parse other more complex lines. Or simply use that code and change the SourceBuilder!

Code generator limitations

The current code generator is not complete, yet adding the missing features would only over-complicate an already hard-to-read code. Some parts of the .tl file should be omitted, because they're "built-in" in the generated code (such as writing booleans, etc.).

In order to make sure that all the generated files will work, please make sure to always comment out these lines in scheme.tl (the latest version can always be found here):

// boolFalse#bc799737 = Bool;
// boolTrue#997275b5 = Bool;
// true#3fedd339 = True;
// vector#1cb5c415 {t:Type} # [ t ] = Vector t;

Also please make sure to rename updates#74ae4240 ... to updates_tg#74ae4240 ... or similar to avoid confusion between the updates folder and the updates.py file!

Plans for the future

If everything works well, this probably ends up being a Python package :)

But as of now, and until that happens, help is highly appreciated!