mirror of
https://github.com/LonamiWebs/Telethon.git
synced 2025-11-04 01:47:27 +03:00
264 lines
8.3 KiB
ReStructuredText
264 lines
8.3 KiB
ReStructuredText
.. _creating-a-client:
|
|
|
|
=================
|
|
Creating a Client
|
|
=================
|
|
|
|
|
|
Before working with Telegram's API, you need to get your 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*) can currently be changed later.
|
|
|
|
4. Click on *Create application* at the end. Remember that your
|
|
**API hash is secret** and Telegram won't let you revoke it.
|
|
Don't post it anywhere!
|
|
|
|
Once that's ready, the next step is to create a ``TelegramClient``.
|
|
This class will be your main interface with Telegram's API, and creating
|
|
one is very simple:
|
|
|
|
.. code-block:: python
|
|
|
|
from telethon import TelegramClient, sync
|
|
|
|
# Use your own values here
|
|
api_id = 12345
|
|
api_hash = '0123456789abcdef0123456789abcdef'
|
|
|
|
client = TelegramClient('some_name', api_id, api_hash)
|
|
|
|
|
|
Note that ``'some_name'`` will be used to save your session (persistent
|
|
information such as access key and others) as ``'some_name.session'`` in
|
|
your disk. This is by default a database file using Python's ``sqlite3``.
|
|
|
|
.. note::
|
|
|
|
It's important that the library always accesses the same session file so
|
|
that you don't need to re-send the code over and over again. By default it
|
|
creates the file in your working directory, but absolute paths work too.
|
|
|
|
|
|
Once you have a client ready, simply `.start()
|
|
<telethon.client.auth.AuthMethods.start>` it:
|
|
|
|
.. code-block:: python
|
|
|
|
client.start()
|
|
|
|
This line connects to Telegram, checks whether the current user is
|
|
authorized or not, and if it's not, it begins the login or sign up process.
|
|
|
|
When you're done with your code, you should always disconnect:
|
|
|
|
.. code-block:: python
|
|
|
|
client = TelegramClient(...)
|
|
try:
|
|
client.start()
|
|
... # your code here
|
|
finally:
|
|
client.disconnect()
|
|
|
|
|
|
You can also use a ``with`` block to achieve the same effect:
|
|
|
|
.. code-block:: python
|
|
|
|
client = TelegramClient(...)
|
|
with client:
|
|
... # your code here
|
|
|
|
# or
|
|
with TelegramClient(...) as client:
|
|
... # your code here
|
|
|
|
|
|
Wrapping it all together:
|
|
|
|
.. code-block:: python
|
|
|
|
from telethon import TelegramClient, sync
|
|
with TelegramClient('session_name', api_id, api_hash) as client:
|
|
... # your code
|
|
|
|
Just two setup lines.
|
|
|
|
.. warning::
|
|
Please note that if you fail to login around 5 times (or change the first
|
|
parameter of the :ref:`TelegramClient <telethon-client>`, which is the session
|
|
name) you will receive a ``FloodWaitError`` of around 22 hours, so be
|
|
careful not to mess this up! This shouldn't happen if you're doing things
|
|
as explained, though.
|
|
|
|
.. note::
|
|
If you want to use a **proxy**, you have to `install PySocks`__
|
|
(via pip or manual) and then set the appropriated parameters:
|
|
|
|
.. code-block:: python
|
|
|
|
import socks
|
|
client = TelegramClient('session_id',
|
|
api_id=12345, api_hash='0123456789abcdef0123456789abcdef',
|
|
proxy=(socks.SOCKS5, 'localhost', 4444)
|
|
)
|
|
|
|
The ``proxy=`` argument should be a tuple, a list or a dict,
|
|
consisting of parameters described `here`__.
|
|
|
|
|
|
Manually Signing In
|
|
*******************
|
|
|
|
.. note::
|
|
|
|
Skip this unless you need more control when connecting.
|
|
|
|
If you need more control, you can replicate what `client.start()
|
|
<telethon.client.auth.AuthMethods.start>` is doing behind the scenes
|
|
for your convenience. The first step is to connect to the servers:
|
|
|
|
.. code-block:: python
|
|
|
|
client.connect()
|
|
|
|
You may or may not be authorized yet. You must be authorized
|
|
before you're able to send any request:
|
|
|
|
.. code-block:: python
|
|
|
|
client.is_user_authorized() # Returns True if you can send requests
|
|
|
|
If you're not authorized, you need to `.sign_in
|
|
<telethon.client.auth.AuthMethods.sign_in>`:
|
|
|
|
.. code-block:: python
|
|
|
|
phone_number = '+34600000000'
|
|
client.send_code_request(phone_number)
|
|
myself = client.sign_in(phone_number, input('Enter code: '))
|
|
# If .sign_in raises PhoneNumberUnoccupiedError, use .sign_up instead
|
|
# If .sign_in raises SessionPasswordNeeded error, call .sign_in(password=...)
|
|
# You can import both exceptions from telethon.errors.
|
|
|
|
.. note::
|
|
|
|
If you send the code that Telegram sent you over the app through the
|
|
app itself, it will expire immediately. You can still send the code
|
|
through the app by "obfuscating" it (maybe add a magic constant, like
|
|
``12345``, and then subtract it to get the real code back) or any other
|
|
technique.
|
|
|
|
``myself`` is your Telegram user. You can view all the information about
|
|
yourself by doing ``print(myself.stringify())``. You're now ready to use
|
|
the client as you wish! Remember that any object returned by the API has
|
|
mentioned ``.stringify()`` method, and printing these might prove useful.
|
|
|
|
As a full example:
|
|
|
|
.. code-block:: python
|
|
|
|
from telethon import TelegramClient, sync
|
|
client = TelegramClient('session_name', api_id, api_hash)
|
|
|
|
client.connect()
|
|
if not client.is_user_authorized():
|
|
client.send_code_request(phone_number)
|
|
me = client.sign_in(phone_number, input('Enter code: '))
|
|
|
|
|
|
Remember that this is the manual process and it's so much easier
|
|
to use the code snippets shown at the beginning of the page.
|
|
|
|
The code shown is just what `.start()
|
|
<telethon.client.auth.AuthMethods.start>` will be doing behind the scenes
|
|
(with a few extra checks), so that you know how to sign in case you want
|
|
to avoid using ``input()`` (the default) for whatever reason. If no phone
|
|
or bot token is provided, you will be asked one through ``input()``. The
|
|
method also accepts a ``phone=`` and ``bot_token`` parameters.
|
|
|
|
You can use either, as both will work. Determining which
|
|
is just a matter of taste, and how much control you need.
|
|
|
|
Remember that you can get yourself at any time with `client.get_me()
|
|
<telethon.client.users.UserMethods.get_me>`.
|
|
|
|
|
|
Two Factor Authorization (2FA)
|
|
------------------------------
|
|
|
|
If you have Two Factor Authorization (from now on, 2FA) enabled on your
|
|
account, calling `.sign_in()
|
|
<telethon.client.auth.AuthMethods.sign_in>` will raise a
|
|
``SessionPasswordNeededError``. When this happens, just use the method
|
|
again with a ``password=``:
|
|
|
|
.. code-block:: python
|
|
|
|
import getpass
|
|
from telethon.errors import SessionPasswordNeededError
|
|
|
|
client.sign_in(phone)
|
|
try:
|
|
client.sign_in(code=input('Enter code: '))
|
|
except SessionPasswordNeededError:
|
|
client.sign_in(password=getpass.getpass())
|
|
|
|
|
|
The mentioned `.start()
|
|
<telethon.client.auth.AuthMethods.start>` method will handle this for you as
|
|
well, but you must set the ``password=`` parameter beforehand (it won't be
|
|
asked).
|
|
|
|
If you don't have 2FA enabled, but you would like to do so through the
|
|
library, use `client.edit_2fa()
|
|
<telethon.client.auth.AuthMethods.edit_2fa>`.
|
|
|
|
Be sure to know what you're doing when using this function and
|
|
you won't run into any problems. Take note that if you want to
|
|
set only the email/hint and leave the current password unchanged,
|
|
you need to "redo" the 2fa.
|
|
|
|
See the examples below:
|
|
|
|
.. code-block:: python
|
|
|
|
from telethon.errors import EmailUnconfirmedError
|
|
|
|
# Sets 2FA password for first time:
|
|
client.edit_2fa(new_password='supersecurepassword')
|
|
|
|
# Changes password:
|
|
client.edit_2fa(current_password='supersecurepassword',
|
|
new_password='changedmymind')
|
|
|
|
# Clears current password (i.e. removes 2FA):
|
|
client.edit_2fa(current_password='changedmymind', new_password=None)
|
|
|
|
# Sets new password with recovery email:
|
|
try:
|
|
client.edit_2fa(new_password='memes and dreams',
|
|
email='JohnSmith@example.com')
|
|
# Raises error (you need to check your email to complete 2FA setup.)
|
|
except EmailUnconfirmedError:
|
|
# You can put email checking code here if desired.
|
|
pass
|
|
|
|
# Also take note that unless you remove 2FA or explicitly
|
|
# give email parameter again it will keep the last used setting
|
|
|
|
# Set hint after already setting password:
|
|
client.edit_2fa(current_password='memes and dreams',
|
|
new_password='memes and dreams',
|
|
hint='It keeps you alive')
|
|
|
|
__ https://github.com/Anorov/PySocks#installation
|
|
__ https://github.com/Anorov/PySocks#usage-1
|