+0
日增长
8,797
stars
2,146
forks
227
watchers
1,079
prs
1,334
issues
88
releases
README
pyTelegramBotAPI
A simple, but extensible Python implementation for the Telegram Bot API.
Both synchronous and asynchronous.
Supported Bot API version:
Official documentation
Official ru documentation
Contents
Getting started
Writing your first bot
Prerequisites
A simple echo bot
General API Documentation
Types
Methods
General use of the API
Message handlers
Edited Message handler
Channel Post handler
Edited Channel Post handler
Callback Query handlers
Shipping Query Handler
Pre Checkout Query Handler
Poll Handler
Poll Answer Handler
My Chat Member Handler
Chat Member Handler
Chat Join request handler
Inline Mode
Inline handler
Chosen Inline handler
Answer Inline Query
Additional API features
Middleware handlers
Custom filters
TeleBot
Reply markup
Advanced use of the API
Using local Bot API Server
Asynchronous TeleBot
Sending large text messages
Controlling the amount of Threads used by TeleBot
The listener mechanism
Using web hooks
Logging
Proxy
Testing
API conformance limitations
AsyncTeleBot
F.A.Q.
How can I distinguish a User and a GroupChat in message.chat?
How can I handle reocurring ConnectionResetErrors?
The Telegram Chat Group
Telegram Channel
More examples
Code Template
Bots using this library
Getting started
This API is tested with Python 3.11-3.15 and PyPy 3.
There are two ways to install the library:
Installation using pip (a Python package manager):
$ pip install pyTelegramBotAPI
Installation from source (requires git):
$ pip install git+https://github.com/eternnoir/pyTelegramBotAPI.git
It is generally recommended to use the first option.
While the API is production-ready, it is still under development and it has regular updates, do not forget to update it regularly by calling
pip install pytelegrambotapi --upgrade
Writing your first bot
Prerequisites
It is presumed that you have obtained an API token with @BotFather. We will call this token TOKEN.
Furthermore, you have basic knowledge of the Python programming language and more importantly the Telegram Bot API.
A simple echo bot
The TeleBot class (defined in \__init__.py) encapsulates all API calls in a single class. It provides functions such as send_xyz (send_message, send_document etc.) and several ways to listen for incoming messages.
Create a file called echo_bot.py.
Then, open the file and create an instance of the TeleBot class.
python
import telebot
bot = telebot.TeleBot("TOKEN", parse_mode=None) You can set parse_mode by default. HTML or MARKDOWN
Note: Make sure to actually replace TOKEN with your own API token.
After that declaration, we need to register some so-called message handlers. Message handlers define filters which a message must pass. If a message passes the filter, the Top issues
#2653Bot API 10.4: widgets support4 comments · 2026-11-11#2624Media upload to fix0 comments · 2026-08-28
Discussions
#2623Media processing13 comments · 2026-08-23#2593Built investment alert bot with pyTelegramBotAPI — open source options flow scanner + price alerts0 comments · 2026-05-13#2576Any chance pyTelegramBotApi can work with MtProto proxy?2 comments · 2026-04-02#2547Embed media group processing at the library level.0 comments · 2026-01-18#2543async send_media_group0 comments · 2026-01-08#2521🤦♀️0 comments · 2025-09-20#2520Sending Video using link Error0 comments · 2025-09-13#2510Using 2 bots in one "py" file!1 comments · 2025-08-12
Latest release
4.37.0 - Bot API 10.3 4.37.0 2026-09-21Bot API support bumped up to v.10.3. Bugfixes and internal redesign.