Pyrogram 0.0.1a0

Telegram MTProto API Client Library for Python

Telegram MTProto API Client Library for Python

Table of Contents

• Overview

• Requirements

  • API Keys

• Installation

• Getting Started

  • Setup

  • Authorization

• Usage

  • Simple API Access

  • Using Raw Functions

• Development

• Documentation

• 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 73).

• 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:

1. Visit https://my.telegram.org/apps and log in with your Telegram Account.

2. Fill out the form to register a new Telegram application.

3. 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:

$ 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 to make API calls.

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:

[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:

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:

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:

  print(client.get_me())

• Send a message to yourself (Saved Messages):

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

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:

  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:

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

Development

The library is still in its early stages, thus lots of functionalities aiming to make working with Telegram’s API easy are yet to be added.

However, being the core functionalities already implemented, every Telegram API method listed in the API scheme can be used right away; the goal is therefore to build a powerful, simple to use, bot-like interface on top of those low-level functions.

Documentation

Soon. For now, have a look at the pyrogram.Client code to get some insights.

Currently you are able to easily:

• send_message

• forward_messages

• edit_message_text

• delete_messages

• send_chat_action

• Some more…

as well as listening for updates and catching API errors.

Contribution

You are very welcome to contribute by either submitting pull requests or reporting issues/bugs as well as suggesting best practices, ideas, enhancements on both code and documentation. Any help is appreciated!

Feedback

Means for getting in touch:

• 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+)