100 lines
3.6 KiB
ReStructuredText
100 lines
3.6 KiB
ReStructuredText
Project Setup
|
|
=============
|
|
|
|
This section provides all the information you need to setup your project with Pyrogram.
|
|
There are a few steps you have to follow before you can actually use the library to make API calls.
|
|
|
|
API Keys
|
|
--------
|
|
|
|
The very first step requires you to obtain a valid Telegram API key.
|
|
If you already have one you can skip this step, otherwise:
|
|
|
|
#. Visit https://my.telegram.org/apps and log in with your Telegram Account.
|
|
#. Fill out the form to register a new Telegram application.
|
|
#. Done. The Telegram API key consists of two parts: the **App api_id** and the **App api_hash**
|
|
|
|
.. important:: This key should be kept secret.
|
|
|
|
Configuration
|
|
-------------
|
|
|
|
There are two ways to configure a Pyrogram application project, and you can choose the one that fits better for you:
|
|
|
|
Create a new ``config.ini`` file at the root of your working directory, copy-paste the following and replace the
|
|
**api_id** and **api_hash** values with `your own <#api-keys>`_. This is the preferred method because allows you
|
|
to keep your credentials out of your code without having to deal with how to load them:
|
|
|
|
.. code-block:: ini
|
|
|
|
[pyrogram]
|
|
api_id = 12345
|
|
api_hash = 0123456789abcdef0123456789abcdef
|
|
|
|
Alternatively, you can pass your API key to Pyrogram by simply using the *api_id* and *api_hash*
|
|
parameters of the Client class. This way you can have full control on how to store and load your credentials:
|
|
|
|
.. code-block:: python
|
|
|
|
from pyrogram import Client
|
|
|
|
client = Client(
|
|
session_name="example",
|
|
api_id=12345
|
|
api_hash="0123456789abcdef0123456789abcdef"
|
|
)
|
|
|
|
.. note:: The examples below assume you have created a ``config.ini`` file, thus they won't show the *api_id*
|
|
and *api_hash* parameters usage.
|
|
|
|
User Authorization
|
|
------------------
|
|
|
|
In order to use the API, Telegram requires that Users be authorized via their phone numbers.
|
|
Pyrogram automatically manages this access, all you need to do is create an instance of
|
|
the :class:`Client <pyrogram.Client>` class by passing to it a ``<session_name>`` of your choice
|
|
(e.g.: "my_account") and call the :meth:`start() <pyrogram.Client.start>` method:
|
|
|
|
.. code-block:: python
|
|
|
|
from pyrogram import Client
|
|
|
|
client = Client("my_account")
|
|
client.start()
|
|
|
|
This starts an interactive shell asking you to input your **phone number** (including your `Country Code`_)
|
|
and the **phone code** you will receive:
|
|
|
|
.. code::
|
|
|
|
Enter phone number: +39**********
|
|
Is "+39**********" correct? (y/n): y
|
|
Enter phone code: 32768
|
|
|
|
After successfully authorizing yourself, a new file called ``my_account.session`` will be created allowing
|
|
Pyrogram executing API calls with your identity. This file will be loaded again when you restart your app,
|
|
and as long as you keep the session alive, Pyrogram won't ask you again to enter your phone number.
|
|
|
|
.. important:: Your *.session file(s) must be kept secret.
|
|
|
|
Bot Authorization
|
|
-----------------
|
|
|
|
Being written entirely from the ground up, Pyrogram is also able to authorize Bots.
|
|
Bots are a special kind of users which also make use of MTProto. This means that you can use Pyrogram to
|
|
execute API calls with a Bot identity.
|
|
|
|
Instead of phone numbers, Bots are authorized via their tokens which are created by BotFather_:
|
|
|
|
.. code-block:: python
|
|
|
|
from pyrogram import Client
|
|
|
|
client = Client("123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11")
|
|
client.start()
|
|
|
|
That's all, no further action is needed. The session file created will be named after the Bot user_id, which is
|
|
``123456.session`` in the example above.
|
|
|
|
.. _`Country Code`: https://en.wikipedia.org/wiki/List_of_country_calling_codes
|
|
.. _BotFather: https://t.me/botfather |