python-telegram-bot — Python Wrapper for the Telegram Bot API

Introduction

python-telegram-bot provides a pure Python, async interface to the Telegram Bot API. It abstracts away HTTP requests and webhook management so you can focus on bot logic with conversation flows, inline queries, and scheduled jobs.

What python-telegram-bot Does

• Wraps every method in the Telegram Bot API with typed Python objects
• Provides ConversationHandler for multi-step user dialogues
• Includes a JobQueue for scheduling recurring or delayed tasks
• Supports webhooks and long-polling out of the box
• Handles rate limiting, retries, and connection pooling automatically

Architecture Overview

The library centers on the Application class, which manages an Updater (fetches updates via polling or webhook), a Dispatcher (routes updates to registered handlers), and a JobQueue (backed by APScheduler). Handlers are matched by type and filters, then executed as async coroutines. Persistence backends can store conversation state across restarts.

Self-Hosting & Configuration

• Install via pip: pip install python-telegram-bot[all] for optional deps
• Obtain a bot token from @BotFather on Telegram
• Set webhooks with application.run_webhook(url=...) behind a reverse proxy
• Use PicklePersistence or DictPersistence for state across restarts
• Deploy as a systemd service, Docker container, or serverless function

Key Features

• Full async/await support built on top of httpx
• Rich filter system for routing messages by text, regex, media type, or custom logic
• Built-in rate limiting that respects Telegram's per-chat and global limits
• Arbitrary callback data for inline keyboards without string parsing
• Extensive type hints and IDE autocompletion support

Comparison with Similar Tools

• Aiogram — also async, lighter weight, but less built-in conversation management
• Telethon — MTProto client for user accounts, not limited to the Bot API
• pyTelegramBotAPI (telebot) — simpler synchronous API, less suitable for complex bots
• node-telegram-bot-api — JavaScript equivalent, callback-based

FAQ

Q: Does it support Telegram Bot API payments? A: Yes, it wraps all payment-related methods including invoices, shipping queries, and pre-checkout handling.

Q: Can I run multiple bots in one process? A: Yes, create multiple Application instances each with their own token and run them concurrently.

Q: What Python versions are supported? A: Version 21.x requires Python 3.9 or later.

Q: How do I handle media groups? A: Use MediaGroupHandler or collect updates sharing the same media_group_id with a short timeout.

Sources

• https://github.com/python-telegram-bot/python-telegram-bot
• https://docs.python-telegram-bot.org/