Welcome to python-telegram’s documentation¶

Client for the tdlib library.

tdlib connects to Telegram over MTProto, the same protocol the official apps use. This library signs in as a full Telegram account with a phone number, and it can do what a regular client can do.

It is not a wrapper around the HTTP Bot API. If you only need a bot, python-telegram-bot is a better fit. You can still sign in as a bot here by passing bot_token instead of phone.

Installation¶

This library requires Python 3.10 or higher, and Linux or macOS. Windows is not supported.

python3 -m pip install python-telegram

Next, register a new Telegram application to get an api_id and an api_hash.

Now you can start using the library: Tutorial.

tdlib¶

python-telegram comes with a precompiled tdlib binary for Linux and macOS, so it works without any extra steps. That binary is dynamically linked and needs specific versions of other system libraries, so it does not work everywhere. Building tdlib yourself is more reliable. See the official build instructions, and do not forget to install it afterwards:

make install

If tdlib is installed system-wide, python-telegram finds it automatically. Otherwise, pass the path to the compiled library. The file is called libtdjson.so on Linux and libtdjson.dylib on macOS:

from telegram.client import Telegram

tg = Telegram(
    # ...
    library_path='/usr/local/lib/libtdjson.so',
)

Docker¶

A Docker image for this library is available here

docker run -i -t --rm \
            -v /tmp/docker-python-telegram/:/tmp/ \
            akhmetov/python-telegram \
            python3 /app/examples/send_message.py $API_ID $API_HASH $PHONE $CHAT_ID $TEXT