eternnoir /pyTelegramBotAPI

Python Telegram bot api.

★ 8,797⑂ 2,146👁 227⑃ 1,079● 1,334▤ 88
PythonGPL-2.0Created 2015-06-26
Download: 4.37.0 - Bot API 10.34.37.0 ↓4.37.02026-09-21
+0
Daily
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

Discussions

Latest release

4.37.0 - Bot API 10.3 4.37.0 2026-09-21
Bot API support bumped up to v.10.3.
Bugfixes and internal redesign.

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON