Telethon is Telegram client implementation in Python which uses the latest available API of Telegram. The project's core only is based on TLSharp, a C# Telegram client implementation.
Before opening an issue about how to use the library, please make sure you have read and followed
the steps mentioned under Using Telethon! A lot of people ask simple questions which will only
be answered as "please see the
README.rst". And you should use the search before posting an issue, too.
Table of contents
- Why Telethon?
- Obtaining your Telegram
- Installing Telethon
- Running Telethon
- Using Telethon
- Advanced uses
Why should I bother with Telethon? There are more mature projects already, such as telegram-cli with even (limited) Python support. 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 entirely 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.
Hungry for more API calls which the
TelegramClient class doesn't seem to have implemented?
Please read Using more than just TelegramClient.
In order to use Telethon, you first need to obtain your very own API ID and Hash:
- Follow this link and login with your phone number.
- Click under API Development tools.
- 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.
- Click on Create application at the end.
Now that you know your
API ID and
Hash, you can continue installing Telethon.
On a terminal, issue the following command:
sudo -H pip install telethon
You're ready to go.
- Install the required
sudo -H pip install pyaes(GitHub, package index)
- Clone Telethon's GitHub repository:
git clone https://github.com/LonamiWebs/Telethon.git
- Enter the cloned repository:
- Run the code generator:
cd telethon_generator && python3 tl_generator.py
If you've installed Telethon via pip, launch an interactive python3 session and enter the following:
>>> from telethon import InteractiveTelegramClient >>> # 'session_id' can be 'your_name'. It'll be saved as your_name.session >>> # Also (obviously) replace the api_id and api_hash with your values ... >>> client = InteractiveTelegramClient('session_id', '+34600000000', ... api_id=12345, api_hash='0123456789abcdef0123456789abcdef') ================== = Initialization = ================== Initializing interactive example... Connecting to Telegram servers... >>> client.run()
If, on the other hand, you've installed Telethon manually, head to the
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_hash and phone number in international format).
Then, simply run
python3 try_telethon.py to start the interactive example.
If you really want to learn how to use Telethon, it is highly advised that you take a look to the InteractiveTelegramClient file and check how it works. This file contains everything you'll need to build your own application, since it shows, among other things:
- Authorizing the user for the first time.
- Support to enter the 2-steps-verification code.
- Retrieving dialogs (chats) and the messages history.
- Sending messages and files.
- Downloading files.
- Updates thread.
If you want a nicer way to see all the available requests and types at your disposal, please check the official Telethon documentation. There you'll find a list of all the methods, types and available constructors.
TelegramClient class should be used to provide a quick, well-documented and simplified starting point.
It is not meant to be a place for all the available Telegram
Request's, because there are simply too many.
However, this doesn't mean that you cannot
invoke all the power of Telegram's API.
Whenever you need to
invoke a Telegram
Request, all you need to do is the following:
result = client.invoke(SomeRequest(...))
You have just
SomeRequest and retrieved its
result! That wasn't hard at all, was it?
Now you may wonder, what's the deal with all the power of Telegram's API? Have a look under
That is everything you can do. You have over 200 API
Request's at your disposal.
However, we don't pretty know how that
result looks like. Easy.
give you a quick overview. Nevertheless, there may be more than a single
result! Let's have a look at
this seemingly innocent
messages.getWebPagePreview#25223e24 message:string = MessageMedia;
Focusing on the end, we can see that the
result of invoking
But how can
MessageMedia exactly look like? It's time to have another look, but this time under
$ tree -P "message_media_*" . ├── tl │ └── types │ ├── message_media_contact.py │ ├── message_media_document.py │ ├── message_media_empty.py │ ├── message_media_geo.py │ ├── message_media_photo.py │ ├── message_media_unsupported.py │ ├── message_media_venue.py │ └── message_media_web_page.py
Those are eight different types! How do we know what exact type it is to determine its properties? A simple
if type(result) == MessageMediaContact: or similar will do. Now you're ready to take advantage of
First of all, you need to understand how the
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!
The code generator will skip the types considered as core types. These types are usually included in almost every programming language, such as boolean values or lists, and also the Telegram True flag, which is not sent but rather used to determine whether that flag should be enabled or not.
Have you found a more updated version of the
scheme.tl file? Those are great news! Updating is as simple
as grabbing the
and replacing the one you can find in this same directory by the updated one.
Don't forget to run
If the changes weren't too big, everything should still work the same way as it did before; but with extra features.
If you want to use Telethon via proxy, you have to install
PySocks (via pip or manual).
Once this is done, pass the proxy settings to the
>>> from telethon import InteractiveTelegramClient >>> import socks >>> client = InteractiveTelegramClient('session_id', '+34600000000', ... api_id=12345, api_hash='0123456789abcdef0123456789abcdef', ... proxy=(socks.SOCKS5, 'localhost', 4444))
proxy= parameter should be a tuple consisting of
(type, 'ip address', port), as described here.