Quick Start

Source Files

This page is generated from the following source files:

• README.md
• examples/echo_bot.py
• examples/asynchronous_telebot/echo_bot.py
• requirements.txt
• examples/mini_app.py
• examples/anonymous_bot.py
• examples/custom_states.py
• examples/payments_example.py
• examples/register_handler.py
• examples/continue_handling.py

Prerequisites

Before starting with pyTelegramBotAPI, ensure the following requirements are met:

Python Version Compatibility: The library is tested with Python 3.9-3.13 and Pypy 3 (README.md:72-72). Earlier Python versions are not supported.

Telegram Bot Token: Obtain an API token from @BotFather on Telegram. This token is required for authenticating bot requests with the Telegram Bot API (README.md:97-97). The token should be stored securely and never committed to version control.

Knowledge Requirements: Basic understanding of Python programming and familiarity with the Telegram Bot API concepts are presumed (README.md:98-98).

Token Configuration Example: In example code, the token is typically stored in a variable before initializing the bot instance:

python
1API_TOKEN = '<api_token>'
2bot = telebot.TeleBot(API_TOKEN)

(examples/echo_bot.py:8-10)

Installation

pyTelegramBotAPI offers multiple installation methods to suit different development environments.

Recommended Installation via pip

The simplest and recommended method uses pip, the Python package manager:

bash
1pip install pyTelegramBotAPI

(README.md:77-78)

Installation from Source

For development or accessing the latest unreleased features, install directly from the GitHub repository:

bash
1pip install git+https://github.com/eternnoir/pyTelegramBotAPI.git

(README.md:82-84)

Keeping the Library Updated

The library receives regular updates. To ensure access to the latest features and bug fixes, update periodically:

bash
1pip install pytelegrambotapi --upgrade

(README.md:89-90)

Core Dependencies

The library relies on the following core dependencies for network operations:

• requests==2.32.4 - HTTP library for synchronous API calls
• aiohttp==3.13.3 - Async HTTP client for AsyncTeleBot functionality
• pytest - Testing framework
• wheel==0.46.2 - Package distribution format

(requirements.txt:1-4)

Creating a TeleBot Instance

The TeleBot class serves as the primary interface for interacting with the Telegram Bot API, encapsulating all API calls within a single class instance.

Basic Initialization

Create a TeleBot instance by passing the API token obtained from BotFather:

python
1import telebot
2
3bot = telebot.TeleBot("TOKEN")

(examples/echo_bot.py:6-10)

Configuration Options

The TeleBot constructor accepts additional parameters for customization. The parse_mode parameter allows setting a default parsing mode for message formatting:

python
1bot = telebot.TeleBot("TOKEN", parse_mode=None)  # Options: HTML, MARKDOWN, or None

(README.md:109-109)

The TeleBot class provides methods such as send_xyz (including send_message, send_document, etc.) and multiple ways to listen for incoming messages (README.md:102-102).

Registering Message Handlers

Message handlers define the logic for processing incoming messages. They use Python decorators to associate filter conditions with handler functions.

Handler Registration Mechanism

A message handler is a function decorated with @bot.message_handler() that processes messages matching specified filters. Each filter must return True for a message to be handled by that function (README.md:177-178).

Command Handlers

Handle specific commands using the commands filter:

python
1@bot.message_handler(commands=['help', 'start'])
2def send_welcome(message):
3    bot.reply_to(message, """\
4Hi there, I am EchoBot.
5I am here to echo your kind words back to you. Just say anything nice and I'll say the exact same thing to you!\
6""")

(examples/echo_bot.py:13-19)

This handler responds to both /start and /help commands with a welcome message.

Lambda Function Filters

Use lambda functions for custom filtering logic. The following handler catches all text messages by returning True for every message:

python
1@bot.message_handler(func=lambda message: True)
2def echo_message(message):
3    bot.reply_to(message, message.text)

(examples/echo_bot.py:22-25)

Handler Execution Order

Handlers are tested in the order they were declared (README.md:131-131). The first handler whose filters all return True will process the message.

Available Filter Types

(README.md:189-195)

Starting the Bot

After registering handlers, start the bot to begin processing incoming messages.

Using infinity_polling

The infinity_polling() method starts a long-polling loop that continuously checks for new updates:

python
1bot.infinity_polling()

(examples/echo_bot.py:28-28)

This method blocks execution and handles reconnection automatically, making it suitable for production deployments (README.md:135-136).

Complete Echo Bot Example

A minimal working echo bot combines all elements:

python
1import telebot
2
3bot = telebot.TeleBot("YOUR_BOT_TOKEN")
4
5@bot.message_handler(commands=['start', 'help'])
6def send_welcome(message):
7    bot.reply_to(message, "Howdy, how are you doing?")
8
9@bot.message_handler(func=lambda message: True)
10def echo_all(message):
11    bot.reply_to(message, message.text)
12
13bot.infinity_polling()

(README.md:138-152)

Running the Bot

Execute the bot script from a terminal:

bash
1python echo_bot.py

(README.md:153-153)

Test the bot by sending /start, /help commands, and arbitrary text messages to verify the echo functionality.

AsyncTeleBot Quick Start

For applications requiring asynchronous operations, pyTelegramBotAPI provides AsyncTeleBot with native async/await support.

AsyncTeleBot Initialization

Import and initialize the async bot using the AsyncTeleBot class:

python
1import asyncio
2from telebot.async_telebot import AsyncTeleBot
3
4bot = AsyncTeleBot('TOKEN')

(examples/asynchronous_telebot/echo_bot.py:5-9)

Async Handler Definition

Handler functions must be defined as async and use await when calling bot methods:

python
1@bot.message_handler(commands=['help', 'start'])
2async def send_welcome(message):
3    text = 'Hi, I am EchoBot.\nJust write me something and I will repeat it!'
4    await bot.reply_to(message, text)

(examples/asynchronous_telebot/echo_bot.py:12-16)

Async Message Handling

The echo handler follows the same pattern with async/await syntax:

python
1@bot.message_handler(func=lambda message: True)
2async def echo_message(message):
3    await bot.reply_to(message, message.text)

(examples/asynchronous_telebot/echo_bot.py:20-22)

Starting the Async Bot

Use asyncio.run() to start the async polling loop:

python
1asyncio.run(bot.polling())

(examples/asynchronous_telebot/echo_bot.py:25-25)

Running Verification

Verifying Synchronous Bot Operation

After starting a bot with python echo_bot.py, verify successful operation by observing the following indicators:

1. No startup errors: The script should start without throwing exceptions
2. Command response: Sending /start or /help should trigger the welcome message
3. Echo response: Any text message should be echoed back by the bot

(README.md:153-153)

Verifying Async Bot Operation

For AsyncTeleBot instances, ensure:

1. The asyncio.run() call executes without errors
2. Handler functions properly use async/await syntax
3. Bot responds to commands and messages as expected

(examples/asynchronous_telebot/echo_bot.py:25-25)

Common Verification Issues

Common Issues and Troubleshooting

Issue 1: Invalid or Missing Bot Token

Symptoms: Authentication errors, 401 Unauthorized responses, bot fails to start.

Cause: The API token is incorrect, expired, or not properly configured in the code.

Solution:

• Verify the token was correctly copied from @BotFather
• Ensure the token is passed as a string to the TeleBot constructor
• Check for extra whitespace or formatting issues in the token string

(examples/echo_bot.py:8-10)

Issue 2: Handlers Not Processing Messages

Symptoms: Bot starts successfully but does not respond to messages or commands.

Cause: Handler filters may not match incoming messages, or handlers are registered after infinity_polling() is called.

Solution:

• Register all handlers before calling infinity_polling()
• Verify filter conditions match expected message types
• Remember that handlers are tested in declaration order

(README.md:131-132)

Issue 3: Connection Reset Errors

Symptoms: Recurring ConnectionResetError exceptions during long-running bot operations.

Cause: Network instability or Telegram API server connection issues.

Solution: The infinity_polling() method handles reconnection automatically. For custom implementations, implement retry logic with exponential backoff (common practice, not explicitly documented in provided sources).

(README.md:63-64)

Issue 4: Async Handler Syntax Errors

Symptoms: TypeError or coroutine warnings when using AsyncTeleBot.

Cause: Missing async keyword on handler functions or missing await on bot method calls.

Solution:

• Declare handlers with async def
• Use await before all bot method calls
• Start the bot with asyncio.run(bot.polling())

(examples/asynchronous_telebot/echo_bot.py:12-22)

Issue 5: Python Version Incompatibility

Symptoms: Import errors or syntax errors related to type hints or async features.

Cause: Using an unsupported Python version.

Solution: Ensure Python 3.9 or higher is installed. Check version with python --version.

(README.md:72-72)

Next Steps

After completing the quick start guide, explore these advanced topics:

Advanced Handler Features

• Custom Filters: Create reusable filter functions for complex message matching logic
• Middleware Handlers: Intercept and process messages before they reach message handlers
• State Management: Implement conversation flows with custom states

Deployment Options

• Webhooks: Configure webhooks for production deployments instead of long-polling
• Local Bot API Server: Set up a local Telegram Bot API server for handling large files and improved performance

Additional Resources

• Official Documentation: Comprehensive API reference at pytba.readthedocs.io (README.md:15-15)
• Example Repository: Additional examples demonstrating payments, mini apps, and advanced patterns
• Telegram Bot API Reference: Official Telegram documentation at core.telegram.org/bots/api