We've just released v12.5
Thanks for anyone who've contributed to this release.

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

New Features:

- Bot.link gives the t.me link of the bot (#1770)

Major Changes:

- Bot API 4.5 and 4.6 support. (#1508, #1723)

Minor changes, CI improvements or bug fixes:

- Remove legacy CI files (#1783, #1791)
- Update pre-commit config file (#1787)
- Remove builtin names (#1792)
- CI improvements (#1808, #1848)
- Support Python 3.8 (#1614, #1824)
- Use stale bot for auto closing stale issues (#1820, #1829, #1840)
- Doc fixes (#1778, #1818)
- Fix typo in edit_message_media (#1779)
- In examples, answer CallbackQueries and use edit_message_text shortcut (#1721)
- Revert accidental change in vendored urllib3 (#1775)

We've just released v12.5.1
Thanks for anyone who've contributed to this release.

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

Minor changes, doc fixes or bug fixes:

- Add missing docs for PollHandler and PollAnswerHandler (#1853)
- Fix wording in Filters docs (#1855)
- Reorder tests to make them more stable (#1835)
- Make ConversationHandler attributes immutable (#1756)
- Make PrefixHandler attributes command and prefix editable (#1636)
- Fix UTC as default tzinfo for Job (#1696)

We've just released v12.6
Thanks for anyone who've contributed to this release.

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

Major Changes:

- Bot API 4.7 support. Note: In Bot.create_new_sticker_set and Bot.add_sticker_to_set, the order of the parameters had be changed, as the png_sticker parameter is now optional. (#1858)

Minor changes, CI improvements or bug fixes:

- Add tests for swtich_inline_query(_current_chat) with empty string (#1635)
- Doc fixes (#1854, #1874, #1884)
- Update issue templates (#1880)
- Favor concrete types over "Iterable" (#1882)
- Pass last valid CallbackContext to TIMEOUT handlers of ConversationHandler (#1826)
- Tweak handling of persistence and update persistence after job calls (#1827)
- Use checkout@v2 for GitHub actions (#1887)

We've just released v12.6.1

This is a bug fix release. As usual, upgrade using pip install -U python-telegram-bot

Thanks for bringing this to our attention:

- Fix serialization of reply_markup in media messages (#1889)

We've just released v12.7
Thanks for anyone who've contributed to this release.

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

Major Changes:

- Bot API 4.8 support. Note: The Dice object now has a second positional argument emoji. This is relevant, if you instantiate Dice objects manually. (#1917)
- Added tzinfo argument to helpers.from_timestamp. It now returns an timezone aware object. This is relevant for Message.{date,forward_date,edit_date}, Poll.close_date and ChatMember.until_date (#1621)

New Features:

- New method run_mothly for the JobQueue (#1705)
- Job.next_t now gives the datetime of the jobs next execution (#1685)

Minor changes, CI improvements, doc fixes or bug fixes:

- Stabalize CI (#1919, #1931)
- Use ABCs @abstractmethod instead of raising NotImplementedError for Handler, BasePersistence and BaseFilter (#1905)
- Doc fixes (#1914, #1902, #1910)

We've just released v12.8
Thanks for anyone who've contributed to this release.

⚠️ As announced in 11/2019, we discontinued support for Python 2 since the start of 2020, as it reached end of life. In correspondence with that, this release now actually removes support for Python 2, making python-telegram-bot a Python 3 only library.
Be advised that if you're still using Python 2 and you want to keep using this library, it's time for you to move on.

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

Major Changes:

- Remove Python 2 support (#1715)
- Bot API 4.9 support (#1980)
- IDs/Usernames of Filters.user and Filters.chat can now be updated (#1757)

Minor changes, CI improvements, doc fixes or bug fixes:

- Update contribution guide and stale bot (#1937)
- Remove NullHandlers (#1913)
- Improve and expand examples (#1943, #1995, #1983, #1997)
- Doc fixes (#1940, #1962)
- Add User.send_poll() shortcut (#1968)
- Ignore private attributes en TelegramObject.to_dict() (#1989)
- Stabilize CI (#2000)

We've just released v13.0. 🥳

It's a major release and brings some major changes.
⚠️ So before upgrading with pip install -U python-telegram-bot as usual, please carefully read the following notes!
You can also find a detailed transition guide on this wiki page.

We'd like to thank everyone, who has contributed to this release!

Major Changes:

v13 presents two massive improvements to our library: Static type hinting and a reworked JobQueue. The first one will be a huge advancement for anyone writing complex programs with an IDE that supports proper auto completion. This will hopefully save you a lot of debugging time. The latter will not directly affect you in most cases. However, we no longer implement the scheduling logic on our own, but use the third party library APSchelduler instead. This enables us to focus our development effort onto other parts of the library. Detailed information on the new JobQueue can be found here.

- Refactor JobQueue (#1981)
- Type Hinting (#1920)

⚠️ v13 also refactors how persistence of Bots is handled. Anyone using PicklePersistence (or a custom persistence class)
should read this paragraph of the transition guide.

- Refactor persistence of Bot instances (#1994)

⚠️ There have been some more reworks and deprecations listed below. Additionally, v13.0 drops Python 3.5, which reached its end of life at the beginning of September 2020.

- Deprecate old-style callbacks, i.e. set use_context=True by default (#2050)
- Refactor Handling of Message VS Update Filters (#2032)
- Deprecate Message.default_quote (#1965)
- Refactor handling of kwargs in Bot methods (#1924)
- Refactor Dispatcher.run_async, deprecating the @run_async decorator (#2051)

New Features:

Besides the big changes, v13 brings some new functionality. Especially noteworthy are the automatic pagination for answer_inline_query, which takes care of the maximum number of InlineResults for you, and the addition of tzinfo to the Defaults setup, which integrates nicely into the new JobQueue.

- Automatic Pagination for answer_inline_query (#2072)
- Defaults.tzinfo (#2042)
- Extend rich comparison of objects (#1724)
- Add Filters.via_bot (#2009)
- Add missing shortcuts (#2043)
- Allow DispatcherHandlerStop in ConversationHandler (#2059)
- Make Errors picklable (#2106 by Delgan)

Minor changes, CI improvements, doc fixes or bug fixes:

Last, but not least, there have been a bunch of smaller additions and improvements to the documentation.

- Fix Webhook not working on Windows with Python 3.8+ (#2067)
- Fix setting thumbs with send_media_group (#2093)
- Make MessageHandler filter for Filters.update first (#2085)
- Fix PicklePersistence.flush() with only bot_data (#2017)
- Add test for clean argument of Updater.start_polling/webhook (#2002 by ikkemaniac)
- Doc fixes, refinements and additions (#2005 by ikkemaniac, #2008, #2089, #2094, #2090)
- CI fixes (#2018, #2061)
- Refine pollbot.py example (#2047 by lrezende)
- Refine Filters in examples (#2027)
- Rename echobotcode> examples (#2025)
- Use Lock-Bot to lock old threads (#2048, #2052, #2049, #2053)

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)