Changelog

[Unreleased]

  • add_update_handler(ANY_UPDATE_HANDLER_TYPE, func) registers a handler for every object tdlib returns, whatever its @type. The responses to your own method calls arrive there too, not only the updates the server pushes (#79).

  • stop can now be called from an update handler. It used to raise RuntimeError: cannot join current thread and leave the tdlib client alive, because the worker joined the thread the handler runs on.

  • idle now returns only after the tdlib client is destroyed. It used to return as soon as stop marked the client stopped, which happens before the listener thread is joined, so a script that exited right after idle could kill the daemon threads part way through the shutdown.

  • send_message takes the rest of the arguments of the tdlib sendMessage method: topic_id, reply_to, options and reply_markup. They are keyword-only and are sent to tdlib as they are, so a message goes to a forum topic with send_message(chat_id, text, topic_id={'@type': 'messageTopicForum', 'forum_topic_id': 2}) (#638).

[2.0.0] - 2026-08-23

  • tdlib 1.8.31 is replaced by tdlib 1.8.66.

  • python-telegram is now published as four platform wheels instead of one py3-none-any wheel: manylinux_2_28_x86_64, manylinux_2_28_aarch64, macosx_11_0_arm64 and macosx_10_15_x86_64. Each bundles a tdlib that links OpenSSL and zlib statically, so it needs nothing from the system.

  • The bundled binary now works on Apple Silicon. The old one was x86_64 only and ctypes refused to load it (#377).

  • The bundled Linux binary no longer needs OpenSSL 1.1, which reached end of life in 2023 and is absent from Debian 12+, Ubuntu 22.04+ and RHEL 9. Importing the library in those images failed with libssl.so.1.1: cannot open shared object file.

  • Installing from the source distribution no longer gives you a tdlib binary. The sdist is the fallback for the platforms the four wheels do not cover, so install tdlib system-wide or pass library_path.

  • The library can now be pointed at a specific tdlib with the PYTHON_TELEGRAM_TDLIB_PATH environment variable. The search order is library_path, then that variable, then a system-wide tdjson, then the bundled binary. Which one was used is logged.

  • When no library can be found or loaded, TDJson raises TDLibNotFoundError instead of a raw dlopen message. It subclasses OSError, which is what ctypes.CDLL used to raise, so existing handlers keep working.

  • Login no longer fails with a ValueError on authorizationStateWaitPremiumPurchase, and an authorization state this library has never heard of now resolves to AuthorizationState.UNKNOWN instead of raising.

Breaking changes, from the tdlib 1.8.66 signatures:

  • get_web_page_instant_view takes only_local instead of force_full. tdlib removed force_full; only_local means something different, “use locally available information only, without any network request”.

  • import_contacts now sends each contact as an importedContact rather than a contact. That is what importContacts takes in 1.8.66.

  • addProxy now nests the server, port and type inside a proxy object. Code that calls call_method('addProxy', ...) directly has to be updated.

[1.0.0] - 2026-07-25

  • Python 3.9 is no longer supported.

  • Added support for Python 3.13 and 3.14.

  • Login no longer fails with a ValueError when tdlib reports an authorization state that AuthorizationState did not know about: authorizationStateWaitEmailAddress, authorizationStateWaitEmailCode, authorizationStateWaitOtherDeviceConfirmation and authorizationStateLoggingOut.

  • Added email authorization support: send_email_address and send_email_code.

  • stop no longer blocks forever when tdlib does not answer, and no longer leaves the client running when tdlib answers with an error. It now waits up to 5 seconds for the session to close, which can be changed with stop(close_timeout=...).

  • Calling a method after stop raises ClientDestroyedError instead of crashing the process. The destroyed tdlib handle was passed to the C library as a NULL pointer.

  • An exception raised by an update handler no longer stops the worker thread. The error is logged and the worker keeps processing the queue.

  • When the handler queue is full, the update is dropped and an error is logged instead of raising queue.Full.

  • get_chats no longer sends the offset_order and offset_chat_id parameters. tdlib removed them from getChats in 1.8.0 and silently ignored them since then, so passing them had no effect. The signature is now get_chats(limit=100, chat_list=None), which also makes it possible to read the archive and chat folders instead of only the main chat list. This is a breaking change for code that passes the offsets.

  • Added load_chats, which wraps the tdlib loadChats method.

[0.19.0] - 2024-06-23

  • Python versions 3.7 and 3.8 are no longer supported.

  • tdlib 1.8.31.

[0.18.0] - 2023-03-13

  • Added support for tdlib > 1.8.5. (thanks to @JleMyP)

[0.17.0] - 2023-01-25

  • Added import_contacts method. (thanks to @vlad-lf)

  • Added markup support. It is now possible to send formatted text (html/markdown and telegram-specific formats, for example hidden spoiler styling) (thanks to @SKY-ALIN)

[0.16.0] - 2022-08-18

  • Search for the system library first, and fallback to the embedded one if the system was not found.

  • Fixed the finding system library mechanism (thanks to @weirdo-neutrino)

  • tdlib v1.8.5

[0.15.0] - 2021-12-03

  • tdlib v1.7.9. Fixes UPDATE_APP_TO_LOGIN errors.

[0.14.0] - 2020-12-17

  • tdlib v1.7.0

[0.13.0] - 2020-11-16

  • Non-blocking login, see examples/get_me_non_blocking_login.py (thanks to @melfnt).

  • Better stop. python-telegram calls close and waits until tdlib is closed.

[0.12.0] - 2020-03-29

  • New example: examples/clear_group_messages.py (thanks to @h4x3rotab)

  • Proxy support (thanks to @h4x3rotab)

  • New methods: delete_messages, get_supergroup_full_info, create_basic_group_chat. (thanks to @h4x3rotab)

  • Fix #67: fixed infinite waiting for a result during login or for an ok result type.

  • New Telegram initialization parameter: use_secret_chats (True by default) (thanks to @DopeforHope)

  • Fix #81: encryption_key for tdlib database encryption is now being sent to tdlib as a base64 encoded string.

[0.11.0] - 2020-02-15

  • tdlib upgraded to v1.6.0 (from this repository)

  • Added a new parameter to the call_method: block=False. If it is set to True, the method waits for the result from tdlib.

  • Added Telegram.get_message method (thanks to @ali-shokoohi)

  • Fixed a race condition when in some cases AsyncResult.wait() could raise TimeoutError or end up in an endless loop. (thanks to @akamaus)

  • Added a new method: get_user.

  • Added Telegram.remove_update_handler function to remove update handlers.

[0.10.0] - 2019-04-10

  • Incompatible Linux library has been changed, now it’s compiled on Ubuntu with libc.

[0.9.0] - 2019-04-05

  • Incompatible default path for files is changed. Now the library uses an md5 hash of the phone number or bot token instead of just a phone number. It should not be noticeable for most cases, but if you rely on locally saved files or database, you need to pass the files_directory parameter to the telegram.client.Telegram.

  • Fixed problem with randomly raised “Database encryption key is needed” errors during login process. (#12)

  • Fixed stop method execution. (#8)

  • Added examples/bot_login.py example.

[0.8.0] - 2019-03-17

  • telegram.client.Telegram now supports any update type with a new method add_update_handler(handler_type, func)

  • tdlib v 1.3.0

  • Fixed problem with openssl in Dockerfile (#4)

[0.7.0]

  • New method getMe with an example.

[0.6.1] - 2018-05-01

  • Fixes for the Linux pre-compiled tdlib library.

[0.6.0] - 2018-05-01

  • Fixes for the Linux pre-compiled tdlib library.

[0.5.0] - 2018-05-01

  • New required parameter in the telegram.client.Telegram: database_encryption_key.

  • Compiled tdlib files now are in the pypi package (Linux and MacOS).

  • Default location of the tdlib’s files changed to /tmp/.tdlib_files/{phone_number}.

  • Now you can define additional optional params:

    • use_test_dc (default False)

    • device_model

    • system_version

    • system_language_code

    • application_version

    • use_message_database (default True)

  • Added new example: chat_stats.py.

[0.4.0] - 2018-04-29

Added two new methods:

  • get_instant_view - get instant view of a web page

  • call_method - call any method with any params

New example: get_instant_view.py

[0.3.1] - 2018-04-29

  • Logging level in the examples changed to INFO.

  • Added new Makefile command: docker-echo-bot.

  • All docker- commands in the Makefile now mount /tmp/ from a host machine to store tdlib’s files.

[0.3.0] - 2018-04-28

  • Added Dockerfile and Makefile with some examples.

  • Changed directory for tdlib files to /tmp/.tdlib_files_{self.phone}/.