Welcome to Python Telegram Bot’s documentation!

Below you can find the documentation for the python-telegram-bot library. except for the .ext package most of the objects in the package reflect the types as defined by the telegram bot api.



Version 12.0.0b1

Released 2019-02-13

First beta release ever. It has been so long since last release that we would like to test the impact before a final release.

We do NOT recommend using this beta release in production.

Major changes:

  • Context based callbacks
  • Persistence
  • PrefixHandler added (Handler overhaul)
  • Deprecation of RegexHandler and edited_messages, channel_post, etc. arguments (Filter overhaul)
  • Various ConversationHandler changes and fixes

See the wiki page at https://git.io/fxJuV for a detailed guide on how to migrate from version 11 to version 12.

Context based callbacks (#1100)

  • Use of pass_ in handlers is deprecated.
  • Instead use use_context=True on Updater or Dispatcher and change callback from (bot, update, others…) to (update, context).
  • This also applies to error handlers Dispatcher.add_error_handler and JobQueue jobs (change (bot, job) to (context) here).
  • For users with custom handlers subclassing Handler, this is mostly backwards compatible, but to use the new context based callbacks you need to implement the new collect_additional_context method.
  • Passing bot to JobQueue.__init__ is deprecated. Use JobQueue.set_dispatcher with a dispatcher instead.
  • Dispatcher makes sure to use a single CallbackContext for a entire update. This means that if an update is handled by multiple handlers (by using the group argument), you can add custom arguments to the CallbackContext in a lower group handler and use it in higher group handler. NOTE: Never use with @run_async, see docs for more info. (#1283)
  • If you have custom handlers they will need to be updated to support the changes in this release.
  • Update all examples to use context based callbacks.

Persistence (#1017)

  • Added PicklePersistence and DictPersistence for adding persistence to your bots.
  • BasePersistence can be subclassed for all your persistence needs.
  • Add a new example that shows a persistent ConversationHandler bot

Handler overhaul (#1114)

  • CommandHandler now only triggers on actual commands as defined by telegram servers (everything that the clients mark as a tabable link).
  • PrefixHandler can be used if you need to trigger on prefixes (like all messages starting with a “/” (old CommandHandler behaviour) or even custom prefixes like “#” or “!”).

Filter overhaul (#1221)

  • RegexHandler is deprecated and should be replaced with a MessageHandler with a regex filter.
  • Use update filters to filter update types instead of arguments (message_updates, channel_post_updates and edited_updates) on the handlers.
  • Completely remove allow_edited argument - it has been deprecated for a while.
  • data_filters now exist which allows filters that return data into the callback function. This is how the regex filter is implemented.
  • All this means that it no longer possible to use a list of filters in a handler. Use bitwise operators instead!


  • Remove run_async_timeout and timed_out_behavior arguments (#1344)
  • Replace with WAITING constant and behavior from states (#1344)
  • Only emit one warning for multiple CallbackQueryHandlers in a ConversationHandler (#1319)
  • Use warnings.warn for ConversationHandler warnings (#1343)
  • Fix unresolvable promises (#1270)

Bug fixes & improvements

  • Handlers should be faster due to deduped logic.
  • Avoid compiling compiled regex in regex filter. (#1314)
  • Add missing left_chat_member to Message.MESSAGE_TYPES (#1336)
  • Make custom timeouts actually work properly (#1330)
  • Add convenience classmethods (from_button, from_row and from_column) to InlineKeyboardMarkup
  • Small typo fix in setup.py (#1306)
  • Add Conflict error (HTTP error code 409) (#1154)
  • Change MAX_CAPTION_LENGTH to 1024 (#1262)
  • Remove some unnecessary clauses (#1247, #1239)
  • Allow filenames without dots in them when sending files (#1228)
  • Fix uploading files with unicode filenames (#1214)
  • Replace http.server with Tornado (#1191)
  • Allow SOCKSConnection to parse username and password from URL (#1211)
  • Fix for arguments in passport/data.py (#1213)
  • Improve message entity parsing by adding text_mention (#1206)

Internal improvements

  • Finally fix our CI builds mostly (too many commits and PRs to list)
  • Use multiple bots for CI to improve testing times significantly.
  • Allow pypy to fail in CI.
  • Remove the last CamelCase CheckUpdate methods from the handlers we missed earlier.

Pre-2019 (up and including to version 11.1.0)

2018-09-01 Released 11.1.0

Fixes and updates for Telegram Passport: (#1198)

  • Fix passport decryption failing at random times
  • Added support for middle names.
  • Added support for translations for documents
  • Add errors for translations for documents
  • Added support for requesting names in the language of the user’s country of residence
  • Replaced the payload parameter with the new parameter nonce
  • Add hash to EncryptedPassportElement

2018-08-29 Released 11.0.0

Fully support Bot API version 4.0! (also some bugfixes :))

Telegram Passport (#1174):

  • Add full support for telegram passport.
    • New types: PassportData, PassportFile, EncryptedPassportElement, EncryptedCredentials, PassportElementError, PassportElementErrorDataField, PassportElementErrorFrontSide, PassportElementErrorReverseSide, PassportElementErrorSelfie, PassportElementErrorFile and PassportElementErrorFiles.
    • New bot method: set_passport_data_errors
    • New filter: Filters.passport_data
    • Field passport_data field on Message
    • PassportData can be easily decrypted.
    • PassportFiles are automatically decrypted if originating from decrypted PassportData.
  • See new passportbot.py example for details on how to use, or go to our telegram passport wiki page for more info
  • NOTE: Passport decryption requires new dependency cryptography.

Inputfile rework (#1184):

  • Change how Inputfile is handled internally
  • This allows support for specifying the thumbnails of photos and videos using the thumb= argument in the different send_ methods.
  • Also allows Bot.send_media_group to actually finally send more than one media.
  • Add thumb to Audio, Video and Videonote
  • Add Bot.edit_message_media together with InputMediaAnimation, InputMediaAudio, and inputMediaDocument.

Other Bot API 4.0 changes:

  • Add forusquare_type to Venue, InlineQueryResultVenue, InputVenueMessageContent, and Bot.send_venue. (#1170)
  • Add vCard support by adding vcard field to Contact, InlineQueryResultContact, InputContactMessageContent, and Bot.send_contact. (#1166)
  • Support new message entities: CASHTAG and PHONE_NUMBER. (#1179)
    • Cashtag seems to be things like $USD and $GBP, but it seems telegram doesn’t currently send them to bots.
    • Phone number also seems to have limited support for now
  • Add Bot.send_animation, add width, height, and duration to Animation, and add Filters.animation. (#1172)

Non Bot API 4.0 changes:

  • Minor integer comparison fix (#1147)
  • Fix Filters.regex failing on non-text message (#1158)
  • Fix ProcessLookupError if process finishes before we kill it (#1126)
  • Add t.me links for User, Chat and Message if available and update User.mention_* (#1092)
  • Fix mention_markdown/html on py2 (#1112)

2018-05-02 Released 10.1.0

Fixes changing previous behaviour:

  • Add urllib3 fix for socks5h support (#1085)
  • Fix send_sticker() timeout=20 (#1088)


  • Add a caption_entity filter for filtering caption entities (#1068)
  • Inputfile encode filenames (#1086)
  • InputFile: Fix proper naming of file when reading from subprocess.PIPE (#1079)
  • Remove pytest-catchlog from requirements (#1099)
  • Documentation fixes (#1061, #1078, #1081, #1096)

2018-04-17 Released 10.0.2

Important fix:

  • Handle utf8 decoding errors (#1076)

New features:

  • Added Filter.regex (#1028)
  • Filters for Category and file types (#1046)
  • Added video note filter (#1067)


  • Fix in telegram.Message (#1042)
  • Make chat_id a positional argument inside shortcut methods of Chat and User classes (#1050)
  • Make Bot.full_name return a unicode object. (#1063)
  • CommandHandler faster check (#1074)
  • Correct documentation of Dispatcher.add_handler (#1071)
  • Various small fixes to documentation.

2018-03-05 Released 10.0.1


  • Fix conversationhandler timeout (PR #1032)
  • Add missing docs utils (PR #912)

2018-03-02 Released 10.0.0

Non backward compatabile changes and changed defaults

  • JobQueue: Remove deprecated prevent_autostart & put() (PR #1012)
  • Bot, Updater: Remove deprecated network_delay (PR #1012)
  • Remove deprecated Message.new_chat_member (PR #1012)
  • Retry bootstrap phase indefinitely (by default) on network errors (PR #1018)

New Features

  • Support v3.6 API (PR #1006)
  • User.full_name convinience property (PR #949)
  • Add send_phone_number_to_provider and send_email_to_provider arguments to send_invoice (PR #986)
  • Bot: Add shortcut methods reply_{markdown,html} (PR #827)
  • Bot: Add shortcut method reply_media_group (PR #994)
  • Added utils.helpers.effective_message_type (PR #826)
  • Bot.get_file now allows passing a file in addition to file_id (PR #963)
  • Add .get_file() to Audio, Document, PhotoSize, Sticker, Video, VideoNote and Voice (PR #963)
  • Add .send_*() methods to User and Chat (PR #963)
  • Get jobs by name (PR #1011)
  • Add Message caption html/markdown methods (PR #1013)
  • File.download_as_bytearray - new method to get a d/led file as bytearray (PR #1019)
  • File.download(): Now returns a meaningful return value (PR #1019)
  • Added conversation timeout in ConversationHandler (PR #895)


  • Store bot in PreCheckoutQuery (PR #953)
  • Updater: Issue INFO log upon received signal (PR #951)
  • JobQueue: Thread safety fixes (PR #977)
  • WebhookHandler: Fix exception thrown during error handling (PR #985)
  • Explicitly check update.effective_chat in ConversationHandler.check_update (PR #959)
  • Updater: Better handling of timeouts during get_updates (PR #1007)
  • Remove unnecessary to_dict() (PR #834)
  • CommandHandler - ignore strings in entities and “/” followed by whitespace (PR #1020)
  • Documentation & style fixes (PR #942, PR #956, PR #962, PR #980, PR #983)

2017-12-08 Released 9.0.0

Breaking changes (possibly)

  • Drop support for python 3.3 (PR #930)

New Features

  • Support Bot API 3.5 (PR #920)


  • Fix race condition in dispatcher start/stop (#887)
  • Log error trace if there is no error handler registered (#694)
  • Update examples with consistent string formatting (#870)
  • Various changes and improvements to the docs.

2017-10-15 Released 8.1.1

  • Fix Commandhandler crashing on single character messages (PR #873).

2017-10-14 Released 8.1.0

New features - Support Bot API 3.4 (PR #865).

Changes - MessageHandler & RegexHandler now consider channel_updates. - Fix command not recognized if it is directly followed by a newline (PR #869). - Removed Bot._message_wrapper (PR #822). - Unitests are now also running on AppVeyor (Windows VM). - Various unitest improvements. - Documentation fixes.

2017-09-01 Released 8.0.0

New features

  • Fully support Bot Api 3.3 (PR #806).
  • DispatcherHandlerStop (see docs).
  • Regression fix for text_html & text_markdown (PR #777).
  • Added effective_attachment to message (PR #766).

Non backward compatible changes

  • Removed Botan support from the library (PR #776).
  • Fully support Bot Api 3.3 (PR #806).
  • Remove de_json() (PR #789).


  • Sane defaults for tcp socket options on linux (PR #754).
  • Add RESTRICTED as constant to ChatMember (PR #761).
  • Add rich comparison to CallbackQuery (PR #764).
  • Fix get_game_high_scores (PR #771).
  • Warn on small con_pool_size during custom initalization of Updater (PR #793).
  • Catch exceptions in error handlerfor errors that happen during polling (PR #810).
  • For testing we switched to pytest (PR #788).
  • Lots of small improvements to our tests and documentation.

2017-07-28 Released 7.0.1

  • Fix TypeError exception in RegexHandler (PR #751).
  • Small documentation fix (PR #749).

2017-07-25 Released 7.0.0

  • Fully support Bot API 3.2.
  • New filters for handling messages from specific chat/user id (PR #677).
  • Add the possibility to add objects as arguments to send_* methods (PR #742).
  • Fixed download of URLs with UTF-8 chars in path (PR #688).
  • Fixed URL parsing for Message text properties (PR #689).
  • Fixed args dispatching in MessageQueue’s decorator (PR #705).
  • Fixed regression preventing IPv6 only hosts from connnecting to Telegram servers (Issue #720).
  • ConvesationHandler - check if a user exist before using it (PR #699).
  • Removed deprecated telegram.Emoji.
  • Removed deprecated Botan import from utils (Botan is still available through contrib).
  • Removed deprecated ReplyKeyboardHide.
  • Removed deprecated edit_message argument of bot.set_game_score.
  • Internal restructure of files.
  • Improved documentation.
  • Improved unitests.


Released 6.1.0

  • Fully support Bot API 3.0
  • Add more fine-grained filters for status updates
  • Bug fixes and other improvements


Released 6.0.3

  • Faulty PyPI release


Released 6.0.2

  • Avoid confusion with user’s urllib3 by renaming vendored urllib3 to ptb_urllib3


Released 6.0.1

  • Add support for User.language_code
  • Fix Message.text_html and Message.text_markdown for messages with emoji


Released 6.0.0


Released 5.3.1

  • Hotfix release due to bug introduced by urllib3 version 1.21


Released 5.3

  • Implement API changes of November 21st (Bot API 2.3)
  • JobQueue now supports datetime.timedelta in addition to seconds
  • JobQueue now supports running jobs only on certain days
  • New Filters.reply filter
  • Bugfix for Message.edit_reply_markup
  • Other bugfixes


Released 5.2

  • Implement API changes of October 3rd (games update)
  • Add Message.edit_* methods
  • Filters for the MessageHandler can now be combined using bitwise operators (& and |)
  • Add a way to save user- and chat-related data temporarily
  • Other bugfixes and improvements


Released 5.1

  • Drop Python 2.6 support
  • Deprecate telegram.Emoji
  • Use ujson if available
  • Add instance methods to Message, Chat, User, InlineQuery and CallbackQuery
  • RegEx filtering for CallbackQueryHandler and InlineQueryHandler
  • New MessageHandler filters: forwarded and entity
  • Add Message.get_entity to correctly handle UTF-16 codepoints and MessageEntity offsets
  • Fix bug in ConversationHandler when first handler ends the conversation
  • Allow multiple Dispatcher instances
  • Add ChatMigrated Exception
  • Properly split and handle arguments in CommandHandler


Released 5.0


Released 4.3.4

  • Fix proxy support with urllib3 when proxy requires auth


Released 4.3.3

  • Fix proxy support with urllib3


Released 4.3.2

  • Fix: Use timeout parameter in all API methods


Released 4.3.1

  • Update wrong requirement: urllib3>=1.10


Released 4.3

  • Use urllib3.PoolManager for connection re-use
  • Rewrite run_async decorator to re-use threads
  • New requirements: urllib3 and certifi


Released 4.2.1

  • Fix CallbackQuery.to_dict() bug (thanks to @jlmadurga)
  • Fix editMessageText exception when receiving a CallbackQuery


Released 4.2

  • Implement Bot API 2.1
  • Move botan module to telegram.contrib
  • New exception type: BadRequest


Released 4.1.2

  • Fix MessageEntity decoding with Bot API 2.1 changes


Released 4.1.1

  • Fix deprecation warning in Dispatcher


Released 4.1

  • Implement API changes from May 6, 2016
  • Fix bug when start_polling with clean=True
  • Methods now have snake_case equivalent, for example telegram.Bot.send_message is the same as telegram.Bot.sendMessage


Released 4.0.3

  • Add missing attribute location to InlineQuery


Released 4.0.2

  • Bugfixes
  • KeyboardReplyMarkup now accepts str again


Released 4.0.1

  • Implement Bot API 2.0
  • Almost complete recode of Dispatcher
  • Please read the Transition Guide to 4.0
  • Changes from 4.0rc1
    • The syntax of filters for MessageHandler (upper/lower cases)
    • Handler groups are now identified by int only, and ordered
  • Note: v4.0 has been skipped due to a PyPI accident


Released 4.0rc1


Released 3.4

  • Move Updater, Dispatcher and JobQueue to new telegram.ext submodule (thanks to @rahiel)
  • Add disable_notification parameter (thanks to @aidarbiktimirov)
  • Fix bug where commands sent by Telegram Web would not be recognized (thanks to @shelomentsevd)
  • Add option to skip old updates on bot startup
  • Send files from BufferedReader


Released 3.3

  • Inline bots
  • Send any file by URL
  • Specialized exceptions: Unauthorized, InvalidToken, NetworkError and TimedOut
  • Integration for botan.io (thanks to @ollmer)
  • HTML Parsemode (thanks to @jlmadurga)
  • Bugfixes and under-the-hood improvements

Very special thanks to Noam Meltzer (@tsnoam) for all of his work!


Released 3.3b1

  • Implement inline bots (beta)


Released 3.2.0

  • Introducing JobQueue (original author: @franciscod)
  • Streamlining all exceptions to TelegramError (Special thanks to @tsnoam)
  • Proper locking of Updater and Dispatcher start and stop methods
  • Small bugfixes


Released 3.1.2

  • Fix custom path for file downloads
  • Don’t stop the dispatcher thread on uncaught errors in handlers


Released 3.1.1

  • Fix a bug where asynchronous handlers could not have additional arguments
  • Add groups and groupdict as additional arguments for regex-based handlers


Released 3.1.0

  • The chat-field in Message is now of type Chat. (API update Oct 8 2015)
  • Message now contains the optional fields supergroup_chat_created, migrate_to_chat_id, migrate_from_chat_id and channel_chat_created. (API update Nov 2015)


Released 3.0.0

  • Introducing the Updater and Dispatcher classes


Released 2.9.2

  • Error handling on request timeouts has been improved


Released 2.9.1

  • Add parameter network_delay to Bot.getUpdates for slow connections


Released 2.9

  • Emoji class now uses bytes_to_native_str from future 3rd party lib
  • Make user_from optional to work with channels
  • Raise exception if Telegram times out on long-polling

Special thanks to @jh0ker for all hard work


Released 2.8.7

  • Type as optional for GroupChat class


Released 2.8.6

  • Adds type to User and GroupChat classes (pre-release Telegram feature)


Released 2.8.5

  • Handles HTTP Bad Gateway (503) errors on request
  • Fixes regression on Audio and Document for unicode fields


Released 2.8.4

  • getFile and File.download is now fully supported


Released 2.8.3

  • Moved Bot._requestURL to its own class (telegram.utils.request)
  • Much better, such wow, Telegram Objects tests
  • Add consistency for str properties on Telegram Objects
  • Better design to test if chat_id is invalid
  • Add ability to set custom filename on Bot.sendDocument(..,filename='')
  • Fix Sticker as InputFile
  • Send JSON requests over urlencoded post data
  • Markdown support for Bot.sendMessage(..., parse_mode=ParseMode.MARKDOWN)
  • Refactor of TelegramError class (no more handling IOError or URLError)


Released 2.8.2

  • Fix regression on Telegram ReplyMarkup
  • Add certificate to is_inputfile method


Released 2.8.1

  • Fix regression on Telegram objects with thumb properties


Released 2.8

  • TelegramError when chat_id is empty for send* methods
  • setWebhook now supports sending self-signed certificate
  • Huge redesign of existing Telegram classes
  • Added support for PyPy
  • Added docstring for existing classes


Released 2.7.1

  • Fixed JSON serialization for message


Released 2.7

  • Added support for Voice object and sendVoice method
  • Due backward compatibility performer or/and title will be required for sendAudio
  • Fixed JSON serialization when forwarded message


Released 2.6.1

  • Fixed parsing image header issue on < Python 2.7.3


Released 2.6.0

  • Depreciation of require_authentication and clearCredentials methods
  • Giving AUTHORS the proper credits for their contribution for this project
  • Message.date and Message.forward_date are now datetime objects


Released 2.5.3

  • telegram.Bot now supports to be unpickled


Released 2.5.2

  • New changes from Telegram Bot API have been applied
  • telegram.Bot now supports to be pickled
  • Return empty str instead None when message.text is empty


Released 2.5.1

  • Moved from GPLv2 to LGPLv3


Released 2.5

  • Fixes logging calls in API


Released 2.4

  • Fixes Emoji class for Python 3
  • PEP8 improvements


Released 2.3

  • Fixes ForceReply class
  • Remove logging.basicConfig from library


Released 2.2

  • Allows debug=True when initializing telegram.Bot


Released 2.1

  • Fix to_dict for Document and Video


Released 2.0

  • Fixes bugs
  • Improves __str__ over to_json()
  • Creates abstract class TelegramObject


Released 1.9

  • Python 3 officially supported
  • PEP8 improvements


Released 1.8

  • Fixes crash when replying an unicode text message (special thanks to JRoot3D)


Released 1.7

  • Fixes crash when username is not defined on chat (special thanks to JRoot3D)


Released 1.6

  • Improvements for GAE support


Released 1.5

  • Fixes randomly unicode issues when using InputFile


Released 1.4

  • requests lib is no longer required
  • Google App Engine (GAE) is supported


Released 1.3

  • Added support to setWebhook (special thanks to macrojames)


Released 1.2

  • CustomKeyboard classes now available
  • Emojis available
  • PEP8 improvements


Released 1.1

  • PyPi package now available


Released 1.0

  • Initial checkin of python-telegram-bot

Indices and tables