|header|

Table of Contents
=================

-   `Overview`_

-   `Requirements`_

    -   `API Keys`_

-   `Installation`_

-   `Getting Started`_

    -   `Setup`_

    -   `Authorization`_

-   `Usage`_

    -   `Simple API Access`_

    -   `Using Raw Functions`_

-   `Contribution`_

-   `Feedback`_

-   `Copyright & License`_


Overview 
========

**Pyrogram** is a Client Library written from the ground up in Python, designed
for Python application developers. It offers simple and complete access to the
`Telegram Messenger API`_. Pyrogram:

-   Provides idiomatic, developer-friendly Python code (either generated or
    hand-written) making the Telegram API simple to use.

-   Handles all the low-level details of communication with the Telegram servers
    by implementing the `MTProto Mobile Protocol v2.0`_.

-   Makes use of the latest Telegram API version (`Layer 72`_).

-   Can be easily installed and upgraded using ``pip``.

-   Requires a minimal set of dependencies.


Requirements
============

-   Operating systems:

    -   Linux

    -   macOS

    -   Windows

-   Python 3.3 or higher.

-   A Telegram API key.

API Keys
--------

To obtain an API key:

#.  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.


Installation
============

You can install and upgrade the library using standard Python tools:

.. code:: shell

    $ pip install --upgrade pyrogram


Getting Started
===============

This section provides all the information you need to start using Pyrogram.
There are a couple of steps you have to follow before you can use the library:

Setup
-----

Create a new ``config.ini`` file at the root of your working directory, paste
the following and replace the **api_id** and **api_hash** values
with `your own`_:

.. code:: ini

    [pyrogram]
    api_id = 12345
    api_hash = 0123456789abcdef0123456789abcdef

Authorization
-------------

Telegram requires that users be authorized in order to use the API.
Pyrogram automatically manages this access, all you need to do is create an
instance of the ``pyrogram.Client`` class and call the ``start`` method:

.. code:: python

    from pyrogram import Client

    client = Client(session_name="example")
    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 ``example.session``
will be created allowing Pyrogram executing API calls with your identity.

**Important**: The ``*.session`` file must be kept secret.


Usage
=====

Having `your session`_ created you can now start playing with the API.

Simple API Access
-----------------

The easiest way to interact with the API is via the ``pyrogram.Client`` class
which exposes `bot-like`_ methods. The purpose of this Client class is to make
it **even simpler** to work with Telegram's API by abstracting the raw functions
listed in the API scheme.

The result is a much cleaner interface that allows you to:

-   Get information about the authorized user:

    .. code:: python

        print(client.get_me())

-   Send a message to yourself (Saved Messages):

    .. code:: python

        client.send_message(chat_id="me", text="Hi there! I'm using Pyrogram")

**Note:** Currently, only a limited number of such high-level methods are
available.

Using Raw Functions
-------------------

If you want **complete**, low-level access to the Telegram API you have to use
the raw ``functions`` and ``types`` exposed by the ``pyrogram.api`` package and
call any Telegram API method you wish using the ``send`` method provided by the
Client class:

-   Update first name, last name and bio:

    .. code:: python

        from pyrogram.api import functions

        client.send(
            functions.account.UpdateProfile(
                first_name="Dan", last_name="Tès",
                about="Bio written from Pyrogram"
            )
        )

-   Share your Last Seen time only with your contacts:

    .. code:: python

        from pyrogram.api import functions, types

        client.send(
            functions.account.SetPrivacy(
                key=types.InputPrivacyKeyStatusTimestamp(),
                rules=[types.InputPrivacyValueAllowContacts()]
            )
        )


Contribution
============

You are welcome to contribute by either submitting pull requests or reporting
issues/bugs as well as suggesting features and best practices.
Any help is appreciated.


Feedback
========

-   `Telegram`_
-   `Github`_
-   `Email`_

Copyright & License
===================

-   Copyright (C) 2017 Dan Tès <https://github.com/delivrance>

-   Licensed under the terms of the
    `GNU Lesser General Public License v3 or later (LGPLv3+)`_
    

.. _`Telegram Messenger API`: https://core.telegram.org/api#telegram-api

.. _`MTProto Mobile Protocol v2.0`: https://core.telegram.org/mtproto

.. _`Layer 72`: compiler/api/source/main_api.tl

.. _`your own`: `API Keys`_

.. _`Country Code`: https://en.wikipedia.org/wiki/List_of_country_calling_codes

.. _`your session`: `Authorization`_

.. _`bot-like`: https://core.telegram.org/bots/api#available-methods

.. _`Telegram`: https://t.me/haskell

.. _`Github`: https://github.com/pyrogram/pyrogram/issues

.. _`Email`: admin@pyrogram.ml

.. _`GNU Lesser General Public License v3 or later (LGPLv3+)`: COPYING.lesser

.. |header| raw:: html

    <h1 align="center">
        <a href="https://github.com">
            <img src="https://www.pyrogram.ml/images/logo.png" alt="Pyrogram">
        </a>
    </h1>

    <p align="center">
        <b>Telegram MTProto API Client Library for Python</b>
        <br><br>
        <a href="https://github.com">
            <img src="https://img.shields.io/badge/scheme-layer%2072-eda738.svg?style=for-the-badge&colorA=262b30"
                alt="Scheme Layer 72">
        </a>
        <a href="https://github.com">
            <img src="https://img.shields.io/badge/mtproto-v2.0-eda738.svg?style=for-the-badge&colorA=262b30"
                alt="MTProto v2.0">
        </a>
    </p>

.. |logo| image:: https://www.pyrogram.ml/images/logo.png
    :target: https://github.com
    :alt: Pyrogram

.. |description| replace:: **Telegram MTProto API Client Library for Python**

.. |scheme| image:: https://img.shields.io/badge/scheme-layer%2072-eda738.svg?style=for-the-badge&colorA=262b30
    :target: https://github.com
    :alt: Scheme Layer 72

.. |mtproto| image:: https://img.shields.io/badge/mtproto-v2.0-eda738.svg?style=for-the-badge&colorA=262b30
    :target: https://github.com
    :alt: MTProto v2.0