Hi there!
Small announcement:

With high regards to @Poolitzer dedication and contribution to the project, we (the active and emeritus maintainers) have decided to give him a more official role/title: Community Liaison.

Thank you Poolitzer for being with us in the last year 😊

The PTB-ecosystem is growing!

Over time, we have seen a lot of awesome code from the community, ranging from custom handlers to additional convenience methods and full grown extension packages, and we're always eager to see how PTB is used for this wide variety of use cases.

While some of you made feature requests or even pull requests to add additional functionality to PTB, we often had to decline them as those features were too specific for a general purpose library and maintaining them would have resulted in a big amount of extra work. Sadly this leads to a lot of code being written all over again by users.

This is why we're happy to announce a new library: ptbcontrib - a place for community based extensions. Let us describe the idea of ptbcontrib in a few bullet points:

• Everyone is welcome to contribute!
• No releases - ptbcontrib is installed directly from GitHub. So no waiting for maintainers to make time for a release
• No limit on 3rd party requirements: Your contribution is welcome to rely on other libraries

We hope to encourage exchange of code within the PTB community with this library and are looking forward to your involvement. You wrote a date picker menu? Cool! An anonymous forward method? We love it. A database-based persistence class? The holy grail!

Have a look at the contribution guide and the example contribution and you're ready to go. Happy coding!

We've just released v13.1.
Thank you to everyone who contributed to this release.

As usual, upgrade using pip install -U python-telegram-bot.

This version brings the long awaited support for Bot API 5.0. PTB now handles all of the long Bot API changelog and provides convenience utilities such as shortcuts for Bot.copy and Filters.sender_chat. Of course PTB also allows you to use your own self hosted Bot API instance. For a full overview on that, please head over to the corresponding wiki page.

Besides the API updates, v13.1 brings Defaults.run_async, making it easy to run all handler callbacks and error handlers asynchronously, and some new filters. Note that Filters.private and Filters.group where deprecated in favor of Filters.chat_type.

For the full list of changes and improvements, please see below.

Major Changes:

• Full support of Bot API 5.0 (#2181, #2186, #2190, #2189, #2183, #2184 by harshil21, #2188, #2185, #2192, #2196, #2193, #2223, #2199, #2187, #2147 by NikitaPirate, #2205)

New Features:

• Add Defaults.run_async (#2210 by starry69)
• Improve and Expand CallbackQuery Shortcuts (#2172)
• Add XOR Filters and make Filters.name a Property (#2179)
• Add Filters.document.file_extension (#2169 by eIGato)
• Add Filters.caption_regex (#2163 by marc0777)
• Add Filters.chat_type (#2128 by GauthamramRavichandran)
• Handle Non-Binary File Input (#2202)

Bug Fixes:

• Improve Handling of Custom Objects in BasePersistence.insert/replace_bot (#2151)
• Fix bugs in replace/insert_bot (#2218)

Minor changes, CI improvements, doc fixes and type hinting:

• Improve Type hinting (#2204, #2118 by harshil21, #2167 by eIGato, #2136)
• Doc Fixes & Extensions (#2201, #2161)
• Use F-Strings Where Possible (#2222)
• Rename kwargs to _kwargs where possible (#2182)
• Comply with PEP561 (#2168)
• Improve Code Quality (#2131)
• Switch Code Formatting to Black (#2122, #2159, #2158)
• Update Wheel Settings (#2142 by michael-k)
• Update timerbot.py to v13.0 (#2149 by timqsh)
• Overhaul Constants (#2137 by NikitaPirate)
• Add Python 3.9 to Test Matrix (#2132)
• Switch Codecov to GitHub Action (#2127)
• Specify Required pytz Version (#2121 by Konano)

Hi all!

In their recent Satellite keynote, GitHub introduced a new feature for repositories: Discussions. This is a tab next to issues, which allows discussion in a more forum like way. This feature is now available in Beta.

We are eager to try it out, as we hope that the new format allows for a searchable and organized way to gather community questions. We activated Discussions on our GitHub repo and invite everyone to both ask their questions there and also answer existing questions. While the Telegram user group will of course still be available, advanced and elaborate questions might be easier to answer in the threaded interface of Discussions.

We are looking forward to your involvement 🙂

We are embracing the future: asyncio support is on its way and it's gonna be legendary!

For those of you who don't know what asyncio does: When calling e.g. bot.send_message(…), your code spends a lot of time waiting for the Telegram API to respond. During that waiting time, other code could be running. So far this was achieved in PTB using multi threading. But:

By now asyncio is a well established standard for concurrency in networking libraries. It can be faster than threaded code and provides some more flexibility. Until the beginning of 2020, PTB still supported Python 2.7, but by now a year has passed and we see an increasing amout of questions on how to integrate asyncio code with PTB. On top of that, we have some plans for features that would heavily benefit from a switch to asyncio.

That is why with the release of version 14, python-telegram-bot will go asyncio!

We are aware that this will be a major breaking change, as

• all callback definitions will have to change from def callback … to async def callback,
• a lot of calls of bot methods will have to change (e.g. message = bot.send_message(…) to message = await bot.sendmessage(…)) and
• projects that use python-telegram-bot in a multi-threaded manner will have to be reworked

However, this switch will also mean a lot of work on the internals of our library and trying to make the change backwards compatible would mean a huge additional effort. We will therefore not provide a compatibility layer. Making this decision was not easy for us, but we hope that it enables us to put our energy in further improvements and enhancements of python-telegram-bot rather than maintaining legacy code for backward of compatibility.

This is, why we're making this announcement this early in our developement process: We don't know yet, when we can release version 14. It may be in a few months or in 2 years - as you know we don't like to give ETAs. But it's important to us to involve the community in the transition and give you a chance to prepare. We will make another announcement when we have a asyncio branch ready. We will give you the opportunity to try the new PTB out and will try to support community based compatibility tools. The actual release will happen later and will be announced beforehand.

We hope that this switch is in your interest. If you have questions or feedback about the announcement, feel free to comment on this GitHub thread. We will try our best to answer your questions and take your comments into account.

In the meantime you can expect some non-breaking improvements. Should Telegram release another API update, we will update our library before going ahead with version 14.

Your PTB Developer Team

»Dread it. Run from it. asyncio still arrives.« - Thanos, ca. 2018, allegedly

We've just released v13.2.
Thank you to everyone who contributed to this release.

As usual, upgrade using pip install -U python-telegram-bot.

This update brings two major improvements. First of, all the convenience shortcuts (like Message.reply_text) now have the full signature of the corresponding bot method. This means that you can leverage auto-completion of your favourite IDE and the type checker of your choice will work even better!

Moreover, we now offer another package: With python-telegram-bot-raw, the pure Telegram API implementation (i.e. the telegram module) is now available as stand-alone package. PTB-Raw does not include telegram.ext and hence has minimal dependencies. By providing PTB-Raw, we hope to make the PTB-ecosystem more attractive for applications that only need the raw API. Please note that PTB-Raw is just the telegram module extracted from PTB. It therefore does not have independent release schedules, changelogs or documentation.

For the full list of changes and improvements, please see below.

Also, we're delighted to have two new developers in our team: @starryboi, @Hoppingturtles, who have already contributed to this release!

Major Changes:

• Introduce python-telegram-bot-raw (#2324)
• Explicit Signatures for Shortcuts (#2240)

New Features:

• Add Missing Shortcuts to Message (#2330 by zeshuaro)
• Rich Comparison for Bot (#2320)
• Add run_async Parameter to ConversationHandler (#2292 by zeshuaro)
• Add New Shortcuts to Chat (#2291)
• Add New Constant MAX_ANSWER_CALLBACK_QUERY_TEXT_LENGTH (#2282)
• Allow Passing Custom Filename For All Media (#2249)
• Handle Bytes as File Input (#2233)

Bug Fixes:

• Fix Escaping in Nested Entities in Message Properties (#2312 by blueset)
• Adjust Calling of Dispatcher.update_persistence (#2285)
• Add quote kwarg to Message.reply_copy (#2232)
• ConversationHandler: Docs & edited_channel_post behavior (#2339)

Minor changes, CI improvements, doc fixes and type hinting:

• Doc Fixes (#2253, #2225)
• Reduce Usage of typing.Any (#2321)
• Extend Deeplinking Example (#2335)
• Add pyupgrade to pre-commit Hooks (#2301)
• Add PR Template (#2299)
• Drop Nightly Tests & Update Badges (#2323)
• Update Copyright (#2289, #2287)
• Change Order of Class DocStrings (#2256)
• Add macOS to Test Matrix (#2266)
• Start Using Versioning Directives in Docs (#2252)
• Improve Annotations & Docs of Handlers (#2243)

⚠️

We were made aware that the latest release v13.2 introduced a bug leading to Defaults being disregarded when using shortcuts like message.reply_text. We are working on a fix and will try to publish a hotfix release shortly. Apologies for the inconvenience.

We've just released v13.3.
Thank you to everyone who contributed to this release.

As usual, upgrade using pip install -U python-telegram-bot.

This update brings the awaited bug fix for Defaults - they are now again correctly handled by the shortcut methods like Message.reply_text. Apart from that, v13.3 includes two more notable changes:

First, the cryptography package is no longer a required dependency. The package is only necessary, if you use Telegram Passports and in that case, you'll now have to install PTB via pip install python-telegram-bot[passport]. Apart from reducing the required dependencies to a minimum, this change was motivated by the recent releases of the cryptography library, which make it harder to install it on some special setups.

Secondly, this release officially deprecated MessageQueue. The framework was intended to allow for easy flood limit control, but was unfortunately never tightly integrated into PTB and as a consequence currently suffers from some bugs (see here for more details). Of course, flood limit control is an important functionality. We're planning to provide a different, better integrated and more customizable mechanism for that after the switch to asyncio in v14.

For the full list of changes and improvements, please see below.

Major Changes:

• Make cryptography Dependency Optional & Refactor Some Tests (#2386, #2370)
• Deprecate MessageQueue (#2393)

Bug Fixes:

• Refactor Defaults Integration (#2363)
• Add Missing telegram.SecureValue to init and Docs (#2398)

Minor changes:

• Doc Fixes (#2359)

We've just released v13.4.
Thank you to everyone who contributed to this release.

As usual, upgrade using pip install -U python-telegram-bot.

This release brings full support for Bot API 5.1.

Moreover, the argument clean of Updater.start_polling/webhook was deprecated in favour of the new argument drop_pending_updates. Updater.start_webhook now also always calls Bot.set_webhook, so you no longer have to worry about that.

Finally, telegram.bot_api_version and telegram.constants.BOT_API_VERSION now include information about which Bot API version your PTB installation supports.

For the full list of changes and improvements, please see below.

Major Changes:

• Full support of Bot API 5.1 (#2424)

Minor changes, CI improvements, doc fixes and type hinting:

• Improve Updater.set_webhook (#2419)
• Doc Fixes (#2404)
• Type Hinting Fixes (#2425)
• Update pre-commit Settings (#2415)
• Fix Logging for Vendored urllib3 (#2427)
• Stabilize Tests (#2409)

We were made aware that the change to start_webhook in the recent release v13.4 was unintentionally breaking.
More precisely, if you have something like

updater.start_webhook(...)
updater.bot.set_webhook('https://python-telegram-bot.org')

in your code, you will have to replace that with

updater.start_webhook(..., webhook_url='https://python-telegram-bot.org')

Because the change is easy to notice (updater.set_webhook will just fail with an error) and the required change is minimal, we will not revert the change.
Apologies for the inconvenience.

We've just released v13.5.
Thank you to everyone who contributed to this release.

As usual, upgrade using pip install -U python-telegram-bot.

This release brings full support for Bot API 5.2.

⚠️ There are a few things to mention about the API update:

• The start_parameter argument of Bot.send_invoice and the corresponding shortcuts is now optional, so the order of parameters had to be changed. Make sure to update your method calls accordingly.
• Service messages about non-bot users joining the chat will be soon removed from large groups. Telegram recommends using the chat_member update as a replacement. Luckily PTB already provides the ChatMemberHandler. To make things even more convenient, we added ChatMemberUpdated.difference(), which tells you exactly what changed for the chat member. Moreover, we added a neat example showcasing ChatMemberHandler and ChatMemberUpdated.difference().
• After the next Bot API update (Bot API 5.3) there will be a one-time change of the value of the field file_unique_id in objects of the type PhotoSize and of the fields small_file_unique_id and big_file_unique_id in objects of the type ChatPhoto.
• ChatAction.{RECORD, UPLOAD}_AUDIO were deprecated in favor of ChatAction.{RECORD, UPLOAD}_VOICE

Apart from the API changes, we also added the new Filters.forwarded_from filter.

For the full list of changes and improvements, please see below.

Major Changes:

• Full support of Bot API 5.2 (#2489).
• Update ChatActions, Deprecating ChatAction.RECORD_AUDIO and ChatAction.UPLOAD_AUDIO (#2460)

New Features:

• Convenience Utilities & Example for Handling ChatMemberUpdated (#2490)
• Filters.forwarded_from (#2446)

Minor changes, CI improvements, Doc fixes and Type hinting:

• Improve Timeouts in ConversationHandler (#2417)
• Stabilize CI (#2480)
• Doc Fixes (#2437)
• Improve Type Hints of Data Filters (#2456)
• Add Two UserWarnings (#2464)
• Improve Code Quality (#2450 by akshgpt7)
• Update Fallback Test-Bots (#2451)
• Improve Examples (#2441, #2448)

We've just released v13.6.
Thank you to everyone who contributed to this release.

As usual, upgrade using pip install -U python-telegram-bot.

This release brings a few major improvements and structural changes, so prepare for a long changelog!

1️⃣ We added __slots__ to (almost) all classes. Head here for detailed info about slots. TL;DR: At least in CPython slots can reduce memory usage and improve performance by fixing which attributes an objects has.

⚠️ For backward compatibility we made sure that code like update.message.my_custom_attribute = 42 will continue to work. However, as adding custom attributes to predefined objects is bad practice anyway, this will raise warnings and we will remove support for this at some point, maybe already in v14.

2️⃣ With the introduction of python-telegram-bot-raw we've already made an effort to make a clear distinction between the raw API implementation and the powerful extensions offered by PTB. This release takes this development one step further by introducing a new class telegram.ext.ExtBot, which is a subclass of telegram.Bot. Functionality that extends the pure bot methods will be implemented in this class from now on. In this light, we also deprecated passing Defaults to telegram.Bot. If you want to use Defaults, please use ExtBot from now on.

ℹ️ This may sound more severe than it is. If you just use Updater(TOKEN) to set up your bot, you will likely not notice this change at all.

3️⃣ We introduced a mechanism that allows you to specify the type of the context argument of the callbacks as well as the types of user/chat/bot_data. To get an idea how this works, please head to the docs of ContextTypes and have a look at the new example.

4️⃣ Everyone who's working with inline buttons and callback_data probably felt limited by the 64 characters limit at some point. Fear no more! This update brings a mechanism that allows you to pass arbitrary objects as callback data. This is done by giving each callback_data an unique ID, passing that ID to Telegram and inserting the callback_data again, when a button is received. This also ties in with persistence (see below).

ℹ️ Because this is a rather advanced feature which might bring some pitfalls, please be sure to check out the wiki page as well as the example on the topic.

5️⃣ There are two updates to the persistence setup to be mentioned. Firstly, we added methods BasePersistence.get/update_callback_data and a corresponding store_callback_data argument, which defaults to False for now. Moreover, we have added methods BasePersistence.refresh_user/chat/bot_data, which will be called for each incoming update (but by default just pass). E.g. if your bot gets data from an external database, this allows you to keep the data up to date. Both the builtin PicklePersistence and DictPersistence handle get/update_callback_data, but pass on refresh_user/chat/bot_data.

Finally, this release adds Filters.attachment and a pattern argument to ChosenInlineResultHandler.

We know that this is a lot to take in, but we hope that the new features make your life easier and help you built more awesome bots.

For the full list of changes and improvements, please see below.

New Features:

• Arbitrary callback_data (#1844)
• Add ContextTypes & BasePersistence.refresh_user/chat/bot_data (#2262)
• Add Filters.attachment (#2528)
• Add pattern Argument to ChosenInlineResultHandler (#2517)

Major Changes:

• Add __slots__ (#2345)

Minor changes, CI improvements, Doc fixes and Type hinting:

• Doc Fixes (#2495, #2510 by Bas ten Berge)
• Add max_connections Parameter to Updater.start_webhook (#2547 by GauthamramRavichandran)
• Fix for Promise.done_callback (#2544)
• Improve Code Quality (#2536, #2454)
• Increase Test Coverage of CallbackQueryHandler (#2520)
• Stabilize CI (#2522, #2537, #2541)
• Fix send_phone_number_to_provider argument for Bot.send_invoice (#2527 by nkrivenko)
• Handle Classes as Input for BasePersistence.replace/insert_bot (#2523)
• Bump Tornado Version and Remove Workaround from #2067 (#2494)

We've just released v13.7.
Thank you to everyone who contributed to this release.

As usual, upgrade using pip install -U python-telegram-bot.

This release brings full support for Bot API 5.3. Note that Bot.get_chat_member and Chat.get_member now return an instance of a subclass of ChatMember.

⚠️ Due to the changes in the API update, we made three kinds of deprecations:

• Bot.{kick_chat_member, get_chat_members_count} were deprecated in favor of the new methods Bot.{ban_chat_member, get_chat_member_count}. Analogously, Chat.{kick_member, get_members_count} were deprecated in favor of the new methods Chat.{ban_member, get_member_count}.
• Because ChatMember is now merely a base class for the 6 new ChatMember* subclasses, most of its arguments and attributes were deprecated (except for status and user, which are common to all subclasses). Once we drop these attributes, this will also affect the subclasses due to inheritance. Therefore, you should check which type of ChatMember* you have and only access the attributes that exist for that type of ChatMember*. For this you can either check the type (isinstance(…)) or check the status.
• As Bot.get_my_commands can now return a different set of commands depending on the scope and language code, it doesn't make sense anymore to cache the commands in Bot.commands. We therefore deprecated this convenience property.

For the full list of changes and improvements, please see below.

Please note that this is the last planned 13.x.y release. We are now starting to work towards v14 and will only make another 13.x.y release if there are serious bugs to be fixed or API updates to implement. As stated in our announcement from January, we don't know how long development for v14 will take. We expect v14 to be ready sometime in 2022.

Major Changes:

• Full support for Bot API 5.3 (#2572)

Bug Fixes:

• Fix Bug in BasePersistence.insert/replace_bot for Objects with __dict__ in their slots (#2561)
• Remove Incorrect Warning About Defaults and ExtBot (#2553)

Minor changes, CI improvements, Doc fixes and Type hinting:

• Type Hinting Fixes (#2552)
• Doc Fixes (#2551)
• Improve Deprecation Warning for __slots__ (#2574)
• Stabilize CI (#2575)
• Fix Coverage Configuration (#2571)
• Better Exception-Handling for BasePersistence.replace/insert_bot (#2564 by zeroone2numeral2)
• Remove Deprecated pass_args from Deeplinking Example (#2550)

In some parts of the world it's already 1st of October and this means: It's time for Hacktoberfest! 💻🥨

Hacktoberfest is an event that encourages open source developers to contribute to repositories through pull requests. If you ever thought about starting coding or giving back to your favourite open source repositories, now is the time! Head over to the hacktoberfest website to learn more about it.

Of course, this is also a great opportunity to contribute to python-telegram-bot 🙂 We already prepared some issues on our repositories, but feel free to begin a hunt for improvements and fixes by yourself! We'd like to especially point out issue #2633, which is about improving our documentation. This issue has several aspects that can be tackled in multiple pull requests and it's great for first time contributors.

⚠️ If you want to tackle an issue, please be sure to
• first comment on that issue so that we can assign you to it and avoid duplicate pull requests for the same issue by several people.
• read this version of the contribution guide
• base your branch on the v14 branch and not on the master branch (see here). This is important, as we're currently working towards a breaking release and the v14 branch already contains some notable changes from master.

True to the Hacktoberfest spirit, we want to try something related to the development of our library: A development group. If you want to start developing something for PTB, you are welcome to join it! We can have some informal discussion about your code changes or provide quick help if you are stuck somewhere.

Some notes regarding this group:
• This is a test. If it doesn't work out/no one uses it, we will shut it down again.
• This will not replace GitHub or the existing groups. It should provide a low barrier entry to the joyful world of PTB development.
• This group is aimed at people who have specific questions regarding the development of PTB and would like to actively participate in the former. Therefore we will keep a closer look at the member list than in the user group.

That out of the way, here is the link: @pythontelegrambotdev

Hacktoberfest is coming to an end and we're happy to report that 13 contributions where proposed by first-time contributors, 10 of which have already been merged. We want to sincerely thank everyone who participated in this event!

Of course contributions are just as welcome after Hacktoberfest ends 🙃 Feel free to join us in the development group chat and we'll be happy to get you started.

We've just released v13.8.
Thank you to everyone who contributed to this release.

As usual, upgrade using pip install -U python-telegram-bot.

This release brings support for Bot API 5.4 as well as some bug fixes.

For the full list of changes and improvements, please see below.

Please note that we are currently working towards v14 and will only make another 13.x.y release if there are serious bugs to be fixed or API updates to implement. As stated in our announcement from January, we don't know how long development for v14 will take. We expect v14 to be ready sometime in 2022.

Major Changes:

• Full support for API 5.4 (#2767)

Minor changes, CI improvements, Doc fixes and Type hinting:

• Create Issue Template Forms (#2689 by abxhr)
• Fix camelCase Functions in ExtBot (#2659 by OctoNezd)
• Fix Empty Captions not Being Passed by Bot.copy_message (#2651 by DonalDuck004)
• Fix Setting Thumbs When Uploading A Single File (#2583 by paradox70)
• Fix Bug in BasePersistence.insert/replace_bot for Objects with __dict__ not in __slots__ (#2603)

We've just released v13.9.
Thank you to everyone who contributed to this release.

As usual, upgrade using pip install -U python-telegram-bot.

This release brings support for Bot API 5.5.
⚠️ There are a few things to mention about the API update. Since API 5.5 is online,

• it is impossible to forward messages from some chats. Use the attributes Message/Chat.has_protected_content to check this.
• users are able to send messages on behalf of channels they own. Bots are expected to use the attribute Message.sender_chat to correctly support such messages.
• Bots are allowed to contact users who sent a join request to a chat where the bot is an administrator with the ChatMemberAdministrator.can_invite_users administrator right – even if the user never interacted with the bot before.
• users can be mentioned by their ID in inline keyboards. This will only work in Telegram versions released after December 7, 2021. Older clients will display unsupported message.

For the full list of changes and improvements, please see below.

Please note that we are currently working towards v14 and will only make another 13.x.y release if there are serious bugs to be fixed or API updates to implement. As stated in our announcement from January, we don't know how long development for v14 will take. We expect v14 to be ready sometime in 2022.

Major Changes:

• Full Support for API 5.5 (#2809)

Minor Changes:

• Adjust Automated Locking of Inactive Issues (#2775)