2016-11-13 17:38:57 +03:00
|
|
|
Telethon
|
|
|
|
========
|
2017-05-29 22:36:51 +03:00
|
|
|
.. epigraph::
|
|
|
|
|
|
|
|
⭐️ Thanks **everyone** who has starred the project, it means a lot!
|
|
|
|
|
|
|
|
**Telethon** is Telegram client implementation in **Python** which uses the latest available API of Telegram.
|
2016-11-13 17:38:57 +03:00
|
|
|
|
2017-05-08 17:08:45 +03:00
|
|
|
Before opening an issue about how to use the library, **please** make sure you have read and followed
|
2017-05-29 22:36:51 +03:00
|
|
|
the steps mentioned under `Using Telethon`_ and are using the latest version! 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.
|
|
|
|
|
|
|
|
If you come here often, you may want to go to the `docs <https://lonamiwebs.github.io/Telethon>`_.
|
2017-05-08 17:08:45 +03:00
|
|
|
|
2016-11-13 17:38:57 +03:00
|
|
|
.. contents:: Table of contents
|
|
|
|
|
|
|
|
Why Telethon?
|
|
|
|
=============
|
|
|
|
.. epigraph::
|
|
|
|
|
|
|
|
Why should I bother with Telethon? There are more mature projects already, such as
|
|
|
|
`telegram-cli <https://github.com/vysheng/tg>`_ with even (limited) Python support. And we have the
|
|
|
|
`official <https://github.com/telegramdesktop/tdesktop>`_ `clients <https://github.com/DrKLO/Telegram>`_!
|
|
|
|
|
|
|
|
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 <https://f-droid.org/repository/browse/?fdfilter=termux&fdid=com.termux>`_). 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.
|
|
|
|
|
2016-11-23 23:03:58 +03:00
|
|
|
Hungry for more API calls which the ``TelegramClient`` class doesn't *seem* to have implemented?
|
|
|
|
Please read `Using more than just TelegramClient`_.
|
2016-11-13 17:38:57 +03:00
|
|
|
|
2016-11-23 23:03:58 +03:00
|
|
|
Obtaining your Telegram ``API ID`` and ``Hash``
|
|
|
|
===============================================
|
2016-11-13 17:38:57 +03:00
|
|
|
In order to use Telethon, you first need to obtain your very own API ID and Hash:
|
|
|
|
|
|
|
|
1. Follow `this link <https://my.telegram.org>`_ 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*)
|
2017-08-22 20:50:57 +03:00
|
|
|
can be changed later as far as I'm aware.
|
2016-11-13 17:38:57 +03:00
|
|
|
4. Click on *Create application* at the end.
|
|
|
|
|
2016-11-23 23:03:58 +03:00
|
|
|
Now that you know your ``API ID`` and ``Hash``, you can continue installing Telethon.
|
2016-11-13 17:38:57 +03:00
|
|
|
|
|
|
|
Installing Telethon
|
|
|
|
===================
|
2017-05-29 22:36:51 +03:00
|
|
|
|
2016-11-23 23:03:58 +03:00
|
|
|
Installing Telethon via ``pip``
|
|
|
|
-------------------------------
|
2016-11-13 17:38:57 +03:00
|
|
|
On a terminal, issue the following command:
|
|
|
|
|
|
|
|
.. code:: sh
|
|
|
|
|
|
|
|
sudo -H pip install telethon
|
|
|
|
|
2017-07-29 11:38:31 +03:00
|
|
|
If you get something like "SyntaxError: invalid syntax" on the ``from error``
|
|
|
|
line, it's because ``pip`` defaults to Python 2. Use `pip3` instead.
|
2017-05-29 22:36:51 +03:00
|
|
|
|
2017-07-29 11:38:31 +03:00
|
|
|
If you already have Telethon installed,
|
|
|
|
upgrade with ``pip install --upgrade telethon``!
|
2016-11-13 17:38:57 +03:00
|
|
|
|
|
|
|
Installing Telethon manually
|
|
|
|
----------------------------
|
|
|
|
|
2017-08-24 19:43:06 +03:00
|
|
|
1. Install the required ``pyaes`` and ``rsa`` modules: ``sudo -H pip install pyaes rsa``
|
2016-11-13 17:38:57 +03:00
|
|
|
(`GitHub <https://github.com/ricmoo/pyaes>`_, `package index <https://pypi.python.org/pypi/pyaes>`_)
|
2016-11-23 23:03:58 +03:00
|
|
|
2. Clone Telethon's GitHub repository: ``git clone https://github.com/LonamiWebs/Telethon.git``
|
|
|
|
3. Enter the cloned repository: ``cd Telethon``
|
2017-06-21 12:27:22 +03:00
|
|
|
4. Run the code generator: ``python3 setup.py gen_tl``
|
2016-11-13 17:38:57 +03:00
|
|
|
5. Done!
|
|
|
|
|
2017-08-24 19:43:06 +03:00
|
|
|
To speed up the crypto part of Telethon, you should also install ``sympy`` and
|
|
|
|
``libssl`` on your computer. This step is optional.
|
|
|
|
|
2016-11-13 17:38:57 +03:00
|
|
|
Running Telethon
|
|
|
|
================
|
|
|
|
If you've installed Telethon via pip, launch an interactive python3 session and enter the following:
|
|
|
|
|
|
|
|
.. code:: python
|
|
|
|
|
2017-06-08 15:00:27 +03:00
|
|
|
>>> from telethon import TelegramClient
|
|
|
|
>>> api_id = 12345
|
|
|
|
>>> api_hash = '0123456789abcdef0123456789abcdef'
|
2017-05-21 14:59:16 +03:00
|
|
|
>>> # 'session_id' can be 'your_name'. It'll be saved as your_name.session
|
2017-06-08 15:00:27 +03:00
|
|
|
... client = TelegramClient('session_id', api_id, api_hash)
|
|
|
|
>>> client.connect()
|
|
|
|
True
|
|
|
|
>>>
|
|
|
|
>>> if not client.is_user_authorized():
|
|
|
|
>>> client.send_code_request('+34600000000')
|
|
|
|
>>> client.sign_in('+34600000000', input('Enter code: '))
|
2016-11-13 17:38:57 +03:00
|
|
|
...
|
2017-06-08 15:00:27 +03:00
|
|
|
>>> # Now you can use the connected client as you wish
|
|
|
|
>>> dialogs, entities = client.get_dialogs(10)
|
|
|
|
>>> print('\n'.join('{}. {}'.format(i, str(e))
|
|
|
|
... for i, e in enumerate(entities)))
|
2016-11-13 17:38:57 +03:00
|
|
|
|
2016-11-23 23:03:58 +03:00
|
|
|
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_id``, ``api_hash`` and phone number in international format).
|
2016-11-13 17:38:57 +03:00
|
|
|
|
2017-06-08 15:00:27 +03:00
|
|
|
Then, simply run ``./try_telethon.py`` to start the interactive example.
|
2016-11-13 17:38:57 +03:00
|
|
|
|
2017-05-08 17:08:45 +03:00
|
|
|
.. _Using Telethon:
|
|
|
|
|
2017-03-20 19:34:51 +03:00
|
|
|
Using Telethon
|
|
|
|
==============
|
2017-05-21 14:59:16 +03:00
|
|
|
If you really want to learn how to use Telethon, it is **highly advised** that
|
2017-03-20 19:34:51 +03:00
|
|
|
you take a look to the
|
2017-06-14 00:05:15 +03:00
|
|
|
`InteractiveTelegramClient <https://github.com/LonamiWebs/Telethon/blob/master/telethon_examples/interactive_telegram_client.py>`_
|
2017-06-08 15:00:27 +03:00
|
|
|
file and check how it works. This file contains everything you'll need to
|
|
|
|
build your own application, since it shows, among other things:
|
2017-03-20 19:34:51 +03:00
|
|
|
|
|
|
|
1. Authorizing the user for the first time.
|
|
|
|
2. Support to enter the 2-steps-verification code.
|
|
|
|
3. Retrieving dialogs (chats) and the messages history.
|
|
|
|
4. Sending messages and files.
|
|
|
|
5. Downloading files.
|
|
|
|
6. Updates thread.
|
|
|
|
|
2017-04-08 15:16:26 +03:00
|
|
|
If you want a nicer way to see all the available requests and types at your
|
|
|
|
disposal, please check the
|
|
|
|
`official Telethon documentation <https://lonamiwebs.github.io/Telethon>`_.
|
|
|
|
There you'll find a list of all the methods, types and available constructors.
|
|
|
|
|
2017-06-08 15:00:27 +03:00
|
|
|
More examples are also available under the ``telethon_examples/`` folder.
|
|
|
|
|
2017-08-17 18:37:27 +03:00
|
|
|
If you're using Telethon under ARM, you may want to install ``sympy`` through
|
|
|
|
``pip`` for a substantial speed-up when generating the keys required to
|
|
|
|
connect to Telegram (you can of course do this on desktop too). See
|
|
|
|
`issue #199 <https://github.com/LonamiWebs/Telethon/issues/199>`_ for more.
|
|
|
|
|
2017-05-29 22:36:51 +03:00
|
|
|
Common errors
|
|
|
|
-------------
|
|
|
|
|
2017-06-10 12:47:51 +03:00
|
|
|
Errors resulting from Telegram queries all subclass the ``RPCError`` class.
|
|
|
|
This class is further specialized into further errors:
|
2017-05-29 22:36:51 +03:00
|
|
|
|
2017-06-10 12:47:51 +03:00
|
|
|
* ``InvalidDCError`` (303), the request must be repeated on another DC.
|
|
|
|
* ``BadRequestError`` (400), the request contained errors.
|
|
|
|
* ``UnauthorizedError`` (401), the user is not authorized yet.
|
|
|
|
* ``ForbiddenError`` (403), privacy violation error.
|
|
|
|
* ``NotFoundError`` (404), make sure you're invoking ``Request``'s!
|
|
|
|
* ``FloodError`` (420), the same request was repeated many times. Must wait ``.seconds``.
|
2017-08-28 15:17:31 +03:00
|
|
|
* ``CdnFileTamperedError``, if the media you were trying to download has been altered.
|
2017-06-10 12:47:51 +03:00
|
|
|
|
|
|
|
Further specialization is also available, for instance, the ``SessionPasswordNeededError``
|
|
|
|
when signing in means that a password must be provided to continue.
|
|
|
|
|
|
|
|
If the error is not recognised, it will only be an ``RPCError``.
|
2017-05-29 22:36:51 +03:00
|
|
|
|
2017-06-09 12:12:56 +03:00
|
|
|
Unless you know what you're doing, you should download media by always using the ``.download_file()``
|
|
|
|
function, which supports a ``str`` or a file handle as parameters. Otherwise, ``.invoke()`` may raise
|
|
|
|
``InvalidDCError`` which you will have to handle, and in turn call ``.invoke_on_dc()`` manually.
|
|
|
|
|
2016-11-13 17:38:57 +03:00
|
|
|
Advanced uses
|
|
|
|
=============
|
|
|
|
|
2016-11-23 23:03:58 +03:00
|
|
|
.. _Using more than just TelegramClient:
|
|
|
|
|
|
|
|
Using more than just ``TelegramClient``
|
|
|
|
---------------------------------------
|
|
|
|
The ``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.
|
2017-07-02 12:56:40 +03:00
|
|
|
Whenever you need to ``call`` a Telegram ``Request``, all you need to do is the following:
|
2016-11-13 17:38:57 +03:00
|
|
|
|
|
|
|
.. code:: python
|
|
|
|
|
2017-07-02 12:56:40 +03:00
|
|
|
result = client(SomeRequest(...))
|
|
|
|
|
|
|
|
# Or the old way:
|
2016-11-13 17:38:57 +03:00
|
|
|
result = client.invoke(SomeRequest(...))
|
|
|
|
|
2017-07-02 12:56:40 +03:00
|
|
|
You have just called ``SomeRequest`` and retrieved its ``result``! That wasn't hard at all, was it?
|
2016-11-23 23:03:58 +03:00
|
|
|
Now you may wonder, what's the deal with *all the power of Telegram's API*? Have a look under ``tl/functions/``.
|
|
|
|
That is *everything* you can do. You have **over 200 API** ``Request``'s at your disposal.
|
2016-11-13 17:38:57 +03:00
|
|
|
|
2016-11-23 23:03:58 +03:00
|
|
|
However, we don't pretty know *how* that ``result`` looks like. Easy. ``print(str(result))`` should
|
|
|
|
give you a quick overview. Nevertheless, there may be more than a single ``result``! Let's have a look at
|
|
|
|
this seemingly innocent ``TL`` definition:
|
2016-11-13 17:38:57 +03:00
|
|
|
|
2016-11-23 23:03:58 +03:00
|
|
|
``messages.getWebPagePreview#25223e24 message:string = MessageMedia;``
|
2016-11-13 17:38:57 +03:00
|
|
|
|
2016-11-23 23:03:58 +03:00
|
|
|
Focusing on the end, we can see that the ``result`` of invoking ``GetWebPagePreviewRequest`` is ``MessageMedia``.
|
|
|
|
But how can ``MessageMedia`` exactly look like? It's time to have another look, but this time under ``tl/types/``:
|
2016-11-13 17:38:57 +03:00
|
|
|
|
|
|
|
.. code:: sh
|
|
|
|
|
|
|
|
$ 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
|
2016-11-23 23:03:58 +03:00
|
|
|
``if type(result) == MessageMediaContact:`` or similar will do. Now you're ready to take advantage of
|
2016-11-13 17:38:57 +03:00
|
|
|
Telegram's polymorphism.
|
|
|
|
|
|
|
|
Tips for porting Telethon
|
|
|
|
-------------------------
|
2016-11-23 23:03:58 +03:00
|
|
|
First of all, you need to understand how the ``scheme.tl`` (``TL`` language) works. Every object
|
2016-11-13 17:38:57 +03:00
|
|
|
definition is written as follows:
|
|
|
|
|
2016-11-23 23:03:58 +03:00
|
|
|
``name#id argument_name:argument_type = CommonType``
|
2016-11-13 17:38:57 +03:00
|
|
|
|
2016-11-23 23:03:58 +03:00
|
|
|
This means that in a single line you know what the ``TLObject`` name is. You know it's unique ID, and you
|
2016-11-13 17:38:57 +03:00
|
|
|
know what arguments it has. It really isn't that hard to write a generator for generating code to any platform!
|
|
|
|
|
2016-11-23 23:03:58 +03:00
|
|
|
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.
|
2016-11-13 17:38:57 +03:00
|
|
|
|
2017-04-14 16:33:05 +03:00
|
|
|
Once you have your own `code generator <telethon_generator/tl_generator.py>`_, start by looking at the
|
2016-11-13 17:38:57 +03:00
|
|
|
`first release <https://github.com/LonamiWebs/Telethon/releases/tag/v0.1>`_ 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*.
|
|
|
|
|
2016-11-23 23:03:58 +03:00
|
|
|
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.
|
2017-01-04 17:20:22 +03:00
|
|
|
Or simply use that code and change the `SourceBuilder <telethon_generator/parser/source_builder.py>`_!
|
2016-11-13 17:38:57 +03:00
|
|
|
|
2016-11-23 23:03:58 +03:00
|
|
|
Notes about the code generator
|
2016-11-13 17:38:57 +03:00
|
|
|
------------------------------
|
2016-11-23 23:03:58 +03:00
|
|
|
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.
|
|
|
|
|
|
|
|
Updating the ``scheme.tl``
|
|
|
|
--------------------------
|
|
|
|
Have you found a more updated version of the ``scheme.tl`` file? Those are great news! Updating is as simple
|
2016-11-13 17:38:57 +03:00
|
|
|
as grabbing the
|
2017-03-20 19:34:51 +03:00
|
|
|
`latest version <https://github.com/telegramdesktop/tdesktop/blob/dev/Telegram/Resources/scheme.tl>`_
|
2016-11-13 17:38:57 +03:00
|
|
|
and replacing the one you can find in this same directory by the updated one.
|
2017-06-21 12:27:22 +03:00
|
|
|
Don't forget to run ``python3 setup.py gen_tl``.
|
2016-11-13 17:38:57 +03:00
|
|
|
|
|
|
|
If the changes weren't too big, everything should still work the same way as it did before; but with extra features.
|
2017-03-20 19:16:34 +03:00
|
|
|
|
2017-03-20 19:34:51 +03:00
|
|
|
Using a proxy
|
|
|
|
-------------
|
2017-03-20 19:16:34 +03:00
|
|
|
If you want to use Telethon via proxy, you have to install
|
2017-03-20 19:34:51 +03:00
|
|
|
`PySocks (via pip or manual) <https://github.com/Anorov/PySocks#installation>`_.
|
|
|
|
Once this is done, pass the proxy settings to the ``TelegramClient`` constructor:
|
2017-03-20 19:16:34 +03:00
|
|
|
|
|
|
|
.. code:: python
|
|
|
|
|
2017-06-08 15:00:27 +03:00
|
|
|
>>> from telethon import TelegramClient
|
2017-03-20 19:16:34 +03:00
|
|
|
>>> import socks
|
2017-06-08 15:00:27 +03:00
|
|
|
>>> client = TelegramClient('session_id',
|
2017-03-20 19:34:51 +03:00
|
|
|
... api_id=12345, api_hash='0123456789abcdef0123456789abcdef',
|
|
|
|
... proxy=(socks.SOCKS5, 'localhost', 4444))
|
2017-03-20 19:16:34 +03:00
|
|
|
|
2017-06-05 07:04:01 +03:00
|
|
|
The ``proxy=`` argument should be a tuple, a list or a dict, consisting of parameters described
|
|
|
|
`here <https://github.com/Anorov/PySocks#usage-1>`_.
|
2017-08-25 16:34:20 +03:00
|
|
|
|
|
|
|
API status
|
|
|
|
----------
|
|
|
|
|
|
|
|
In an attempt to help everyone who works with the Telegram API, Telethon
|
|
|
|
will by default report all Remote Procedure Call errors to
|
|
|
|
`PWRTelegram <https://pwrtelegram.xyz/>`_, a public database anyone
|
|
|
|
can query, made by `Daniil <https://github.com/danog>`_. All the information
|
|
|
|
sent is a ``GET`` request with the error code, error message and method used.
|
|
|
|
|
|
|
|
If you still would like to opt out, simply set
|
|
|
|
``client.session.report_errors = False`` to disable this feature. However
|
|
|
|
Daniil would really thank you if you helped him (and everyone) by keeping
|
|
|
|
it on!
|