python-telegram-bot

python-telegram-bot is a pure Python interface to the Telegram Bot API, covering every type and method of the API surface with generated, type-hinted classes. Built on top of the raw API bindings, its telegram.ext submodule adds an opinionated application framework: an Application that owns the event loop, an Updater for polling or webhooks, a family of Handler classes for routing updates by type or content, a JobQueue for scheduled work, and pluggable persistence for conversation state.

The library is used to build everything from simple command-and-reply bots to long-running, stateful conversational bots and business integrations, and it tracks new Telegram Bot API releases closely, typically shipping compatibility updates within days of an API changelog.

What You Get

• Complete, type-hinted bindings for every Telegram Bot API type and method, kept in sync with new Bot API releases
• An Application/Updater runtime that manages polling or webhook delivery, update dispatch, and graceful shutdown
• A library of Handler classes (commands, messages, callback queries, inline queries, chat member updates, and more) plus ConversationHandler for multi-step flows
• Built-in JobQueue for scheduled and repeating tasks, backed by APScheduler as an optional extra
• Pluggable persistence (PicklePersistence, DictPersistence, or a custom BasePersistence) for surviving restarts with conversation and user data intact
• Optional extras for HTTP/2, SOCKS5 proxies, webhook servers (Tornado), rate limiting (aiolimiter), and Telegram Passport (cryptography)

Common Use Cases

• Command-and-reply bots that respond to slash commands and plain messages
• Stateful conversational bots that walk users through multi-step flows via ConversationHandler
• Webhook-based bots deployed behind a web server or serverless function instead of long polling
• Scheduled/recurring notifications and reminders driven by the built-in JobQueue
• Business and support-desk integrations that use inline keyboards, callback queries, and payments

Under The Hood

Architecture The library is split into a generated, data-only API layer (telegram/_*.py, e.g. _bot.py, _chat.py, _message.py) and an application framework in telegram/ext/. Application (telegram/ext/_application.py) is the runtime core: it owns an ExtBot (a rate-limiting-aware subclass of the raw Bot), an Updater for fetching updates via polling or webhooks, a JobQueue, and an ordered group of BaseHandler subclasses it dispatches each Update through. ApplicationBuilder (telegram/ext/_applicationbuilder.py) is a fluent builder that wires these collaborators together along with an injectable BasePersistence implementation, so persistence, rate limiting, and the HTTP transport are all swappable without touching Application itself. Handlers live under telegram/ext/_handlers/, each a thin BaseHandler subclass whose check_update/handle_update pair decides applicability and dispatches to user callbacks, with ConversationHandler composing several handlers into a per-user state machine. If Bot or ExtBot changed shape, every handler and the persistence layer would need to follow since they all consume Update/Bot objects directly rather than through an abstraction.

Tech Stack The only hard runtime dependency is httpx (0.27-0.29) via telegram.request._httpxrequest.HTTPXRequest, the default async transport implementing an abstract BaseRequest. Optional extras are cleanly isolated behind pyproject.toml’s [project.optional-dependencies]: cryptography for Telegram Passport decryption, APScheduler for JobQueue, tornado for the built-in webhook server, aiolimiter for AIORateLimiter, and cachetools for arbitrary callback-data caching. The project builds with hatchling, is developed with uv (uv.lock committed), and derives its version dynamically from telegram/_version.py.

Code Quality The test suite under tests/ spans 247 files exercising both the raw API bindings and the ext framework, run with pytest, pytest-asyncio, and pytest-xdist for parallelism, with branch coverage tracked via pytest-cov/codecov.yml. Typing is enforced strictly: mypy runs with disallow_untyped_defs, disallow_incomplete_defs, and disallow_untyped_decorators across src/, backed by an extensive ruff rule selection (including flake8-bugbear, pyupgrade, and pydocstyle in Google convention) and pylint, all wired into pre-commit hooks. CI (.github/workflows/) runs unit tests, a test_official job that cross-checks the library’s API surface against Telegram’s own documentation, monthly type-completeness checks, and a docs link checker — a notably thorough setup for an API-wrapper library.

API Design The public API favors ergonomic shortcuts over raw verbosity — e.g. Message.reply_text(...) instead of manually addressing Bot.send_message with the chat ID — while every method and type carries full type hints and Sphinx docstrings with versionadded/versionchanged annotations tracking Bot API compatibility across releases. Getting a minimal bot running takes only a handful of lines (ApplicationBuilder().token(...).build() plus one handler), while the same builder exposes progressively more configuration (persistence, rate limiter, custom request transport) for advanced setups without changing the basic entry point.