{"id":1021,"library":"python-telegram-bot","title":"python-telegram-bot","description":"This library provides a pure Python, asynchronous interface for the Telegram Bot API. It's compatible with Python versions 3.10+. It features convenience methods, shortcuts, and high-level classes within the `telegram.ext` submodule to simplify bot development. It supports all types and methods of the Telegram Bot API 9.5 and receives frequent updates, with new releases typically coming out every few weeks/months.","status":"active","version":"22.7","language":"python","source_language":"en","source_url":"https://github.com/python-telegram-bot/python-telegram-bot","tags":["telegram","bot","async","wrapper","chatbot"],"install":[{"cmd":"pip install python-telegram-bot","lang":"bash","label":"Install stable version"},{"cmd":"pip install \"python-telegram-bot[all]\"","lang":"bash","label":"Install with all optional dependencies"}],"dependencies":[{"reason":"Required for telegram.request.HTTPXRequest, the default networking backend.","package":"httpx","optional":false},{"reason":"Optional, for rate limiting functionality (`[rate-limiter]`).","package":"aiolimiter","optional":true},{"reason":"Optional, for webhook functionality (`[webhooks]`).","package":"tornado","optional":true},{"reason":"Optional, for callback data caching (`[callback-data]`).","package":"cachetools","optional":true},{"reason":"Optional, for job queue functionality (`[job-queue]`).","package":"APScheduler","optional":true},{"reason":"Optional, for Socks5 proxy support (`[socks]`).","package":"httpx[socks]","optional":true},{"reason":"Optional, for HTTP/2 support (`[http2]`).","package":"httpx[http2]","optional":true},{"reason":"Optional, for Telegram Passport related functionality (`[passport]`).","package":"cryptography","optional":true}],"imports":[{"symbol":"Application","correct":"from telegram.ext import Application"},{"symbol":"CommandHandler","correct":"from telegram.ext import CommandHandler"},{"symbol":"MessageHandler","correct":"from telegram.ext import MessageHandler"},{"symbol":"filters","correct":"from telegram.ext import filters"},{"note":"While CallbackContext still exists, ContextTypes is the modern and type-hinted way to refer to the context object in handler callbacks, especially since v20.0.","wrong":"from telegram.ext import CallbackContext","symbol":"ContextTypes","correct":"from telegram.ext import ContextTypes"},{"symbol":"Update","correct":"from telegram import Update"},{"note":"The Updater class was removed in version 20.0. Use Application.builder() and Application.run_polling() or run_webhook() instead.","wrong":"from telegram.ext import Updater","symbol":"Updater","correct":"N/A"}],"quickstart":{"code":"import os\nimport logging\nfrom telegram import Update\nfrom telegram.ext import Application, CommandHandler, MessageHandler, filters, ContextTypes\n\n# Enable logging\nlogging.basicConfig(\n    format=\"%(asctime)s - %(name)s - %(levelname)s - %(message)s\", level=logging.INFO\n)\n# set higher logging level for httpx to avoid all GET and POST requests being logged\nlogging.getLogger(\"httpx\").setLevel(logging.WARNING)\n\nlogger = logging.getLogger(__name__)\n\n\nasync def start_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:\n    \"\"\"Sends a message when the command /start is issued.\"\"\"\n    user = update.effective_user\n    await update.message.reply_html(\n        f\"Hi {user.mention_html()}!\\nI'm an echo bot. Send me anything!\",\n    )\n\n\nasync def help_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:\n    \"\"\"Sends a message when the command /help is issued.\"\"\"\n    await update.message.reply_text(\"Help! Send me a message and I will echo it back!\")\n\n\nasync def echo(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:\n    \"\"\"Echo the user message.\"\"\"\n    await update.message.reply_text(update.message.text)\n\n\nasync def main() -> None:\n    \"\"\"Start the bot.\"\"\"\n    # Replace with your bot's token from BotFather. Get from environment variable.\n    BOT_TOKEN = os.environ.get('TELEGRAM_BOT_TOKEN')\n    if not BOT_TOKEN:\n        raise ValueError(\"TELEGRAM_BOT_TOKEN environment variable not set.\")\n\n    # Create the Application and pass it your bot's token.\n    application = Application.builder().token(BOT_TOKEN).build()\n\n    # On different commands - add handlers\n    application.add_handler(CommandHandler(\"start\", start_command))\n    application.add_handler(CommandHandler(\"help\", help_command))\n\n    # On non command messages - echo the message on Telegram\n    application.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo))\n\n    # Run the bot until the user presses Ctrl-C\n    logger.info(\"Starting bot polling...\")\n    await application.run_polling(allowed_updates=Update.ALL_TYPES)\n\n\nif __name__ == \"__main__\":\n    import asyncio\n    asyncio.run(main())\n","lang":"python","description":"This quickstart code sets up a simple echo bot that replies to `/start` and `/help` commands, and echoes back any other text message it receives. It demonstrates the use of `Application`, `CommandHandler`, and `MessageHandler` with filters. Your bot token should be provided via the `TELEGRAM_BOT_TOKEN` environment variable."},"warnings":[{"fix":"Rewrite bot initialization to use `Application.builder().build()`, update handler functions to be `async def`, and adjust file download calls. Install optional dependencies if needed, e.g., `pip install \"python-telegram-bot[job-queue]\"`.","message":"Version 20.0 introduced significant breaking changes. The `Updater` class was removed and replaced by `Application`. The architecture shifted to `asyncio`, requiring async/await for handler functions. The `File.download` method was split into `File.download_to_drive` and `File.download_to_memory`. Most third-party dependencies became optional, requiring explicit installation for certain features.","severity":"breaking","affected_versions":">=20.0.0"},{"fix":"Design your bot with asyncio concurrency in mind. If you must use threads for specific tasks, ensure proper synchronization for PTB components or isolate PTB interactions to the main async loop.","message":"Since v20.0, `python-telegram-bot` is built on `asyncio` and is generally not thread-safe. Avoid using `telegram.ext.Application/Updater.update_queue`, `telegram.ext.ConversationHandler.check/handle_update`, `telegram.ext.CallbackDataCache`, and runtime modifications to `telegram.ext.filters` classes in multi-threaded environments to prevent race conditions.","severity":"gotcha","affected_versions":">=20.0.0"},{"fix":"Configure timeouts using `ApplicationBuilder` methods (e.g., `ApplicationBuilder().read_timeout(seconds)`) or by specifying them via `telegram.Bot.get_updates_request`.","message":"Timeout arguments (`read_timeout`, `write_timeout`, `connect_timeout`, `pool_timeout`) for `Application.run_polling()` were removed in v22.0.","severity":"deprecated","affected_versions":">=22.0.0"},{"fix":"Set the environment variable `PTB_TIMEDELTA=true` or `PTB_TIMEDELTA=1` to opt into `datetime.timedelta` objects now. Update your code to handle `timedelta` objects for these attributes.","message":"Attributes representing durations/time periods (e.g., `ChatFullInfo.slow_mode_delay`) are migrating from `int` to `datetime.timedelta`. While `int` is currently supported, it's deprecated and will be removed in a future major version.","severity":"deprecated","affected_versions":">=22.6.0"},{"fix":"Always include relevant new update types in the `allowed_updates` parameter, or use `allowed_updates=Update.ALL_TYPES` if you want to receive all available updates by default.","message":"For new Telegram Bot API update types (e.g., `MESSAGE_REACTION_COUNT`, `BUSINESS_CONNECTION`), you must explicitly list them in `Application.run_polling(allowed_updates=...)` or `Bot.set_webhook(allowed_updates=...)` to receive them. Using `Update.ALL_TYPES` is generally safer for comprehensive update reception.","severity":"gotcha","affected_versions":">=13.4 (for older types), >=21.1 (for newer types)"},{"fix":"Upgrade to v22.5.0 or later. For future compatibility, always use keyword arguments when calling methods, especially those with many parameters or new parameters in recent versions.","message":"Version 22.5 addressed a breaking change accidentally introduced in v22.4 regarding the `ReplyParameters` class, where adding a new parameter broke positional arguments.","severity":"breaking","affected_versions":"22.4.0"}],"env_vars":null,"last_verified":"2026-05-12T22:42:15.125Z","next_check":"2026-06-27T00:00:00.000Z","problems":[{"fix":"Update your code to use `Application.builder().token('YOUR_TOKEN').build()` and `application.run_polling()` or `application.run_webhook()` instead of `Updater`.","cause":"The `Updater` class was removed in `python-telegram-bot` version 20.0 and later, replaced by the `Application` class for managing the bot's lifecycle.","error":"ImportError: cannot import name 'Updater' from 'telegram.ext'"},{"fix":"Access the bot instance directly using `context.bot` (e.g., `await context.bot.send_message(...)`) instead of `context.dispatcher.bot` or `update.dispatcher.bot`.","cause":"In `python-telegram-bot` version 20.0 and later, the `Dispatcher` object was removed, and the `bot` instance is now directly accessible via `context.bot` within handlers.","error":"AttributeError: 'CallbackContext' object has no attribute 'dispatcher'"},{"fix":"Import `filters` from `telegram.ext` and use its attributes (e.g., `filters.TEXT`, `filters.COMMAND`) directly within `MessageHandler` or other handlers. For example, `MessageHandler(filters.TEXT & ~filters.COMMAND, my_handler)`.","cause":"The `MessageFilter` class was replaced by the `filters` module in `python-telegram-bot` version 20.0 and later, offering a more granular way to filter updates.","error":"NameError: name 'MessageFilter' is not defined"},{"fix":"Ensure that any function called with `await` is an `async def` function and that it actually returns an awaitable object. Check for typos or missing `await`s on functions like `context.bot.send_message`.","cause":"This error typically indicates that an `await` keyword was used on a function call that either returned `None` or did not return a valid awaitable (coroutine) object, often because the function itself was not defined as `async` or was called incorrectly.","error":"TypeError: object NoneType can't be used in 'await' expression"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"22.7","cli_name":"","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"all","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.89,"mem_mb":22.5,"disk_size":"50.7M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"all","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.91,"mem_mb":22.3,"disk_size":"49.6M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.61,"mem_mb":15.9,"disk_size":"28.8M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.6,"mem_mb":15.9,"disk_size":"28.7M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"all","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":4,"import_time_s":0.71,"mem_mb":22.5,"disk_size":"51M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"all","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.7,"mem_mb":22.3,"disk_size":"50M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.4,"import_time_s":0.4,"mem_mb":15.9,"disk_size":"29M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.47,"mem_mb":15.9,"disk_size":"29M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"all","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":1.5,"mem_mb":24.5,"disk_size":"55.4M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"all","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.6,"mem_mb":24.4,"disk_size":"54.2M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":1.19,"mem_mb":17.5,"disk_size":"31.8M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.31,"mem_mb":17.5,"disk_size":"31.8M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"all","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":4,"import_time_s":1.24,"mem_mb":24.5,"disk_size":"56M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"all","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.28,"mem_mb":24.4,"disk_size":"55M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.5,"import_time_s":1.03,"mem_mb":17.5,"disk_size":"32M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.02,"mem_mb":17.5,"disk_size":"32M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"all","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":1.34,"mem_mb":24.1,"disk_size":"46.5M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"all","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.48,"mem_mb":24,"disk_size":"45.4M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":1.05,"mem_mb":17.5,"disk_size":"23.3M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.23,"mem_mb":17.5,"disk_size":"23.3M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"all","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":3.6,"import_time_s":1.32,"mem_mb":24.1,"disk_size":"47M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"all","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.54,"mem_mb":24,"disk_size":"46M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.3,"import_time_s":1.06,"mem_mb":17.5,"disk_size":"24M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.25,"mem_mb":17.5,"disk_size":"24M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"all","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":1.38,"mem_mb":25.1,"disk_size":"45.8M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"all","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.47,"mem_mb":24.9,"disk_size":"44.5M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":1.13,"mem_mb":18.4,"disk_size":"22.6M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.25,"mem_mb":18.4,"disk_size":"22.4M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"all","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":3.6,"import_time_s":1.28,"mem_mb":25.1,"disk_size":"46M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"all","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.51,"mem_mb":24.9,"disk_size":"45M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.3,"import_time_s":1.04,"mem_mb":18.4,"disk_size":"23M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.23,"mem_mb":18.4,"disk_size":"23M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"all","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.77,"mem_mb":21.4,"disk_size":"50.3M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"all","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.8,"mem_mb":21.3,"disk_size":"49.3M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.49,"mem_mb":15.6,"disk_size":"27.9M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.52,"mem_mb":15.6,"disk_size":"27.9M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"all","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":4.8,"import_time_s":0.65,"mem_mb":22.1,"disk_size":"51M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"all","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.7,"mem_mb":21.3,"disk_size":"50M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.8,"import_time_s":0.42,"mem_mb":15.6,"disk_size":"28M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.43,"mem_mb":15.6,"disk_size":"28M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}