pyTelegramBotAPI

Warnings

• breaking Major changes in the official Telegram Bot API, while often accommodated by library updates, can sometimes introduce breaking changes requiring code migration. Always review the `pyTelegramBotAPI` changelog and Telegram Bot API release notes when upgrading, especially across significant version bumps.
  Fix: Consult the official pyTelegramBotAPI GitHub releases and Telegram Bot API documentation for migration guides. Update your bot's code to align with new API specifications.
• deprecated The `reply_to_message_id`, `allow_sending_without_reply`, and `disable_web_page_preview` parameters in `bot.send_message()` and similar methods have been deprecated by Telegram. While they might still function, it's recommended to use newer alternatives for reply parameters and link previews.
  Fix: For replies, use `reply_parameters` instead of `reply_to_message_id`. For web page previews, refer to the current Telegram Bot API documentation for `link_preview_options`.
• gotcha The library offers both synchronous (`telebot.TeleBot`) and asynchronous (`telebot.async_telebot.AsyncTeleBot`) implementations. Mixing them incorrectly or using `TeleBot` with long-running operations in handlers without threading can block your bot. `TeleBot`'s `infinity_polling()` is synchronous, while `AsyncTeleBot` typically uses `asyncio.run(bot.polling())`.
  Fix: For synchronous bots, ensure handlers are fast or delegate long tasks to separate threads/processes (e.g., by initializing `TeleBot(threaded=True)`). For I/O-bound tasks and better scalability, consider using `AsyncTeleBot` and `async`/`await` patterns consistently throughout your bot's logic.
• gotcha The `Message` object received by handlers has its `from` attribute renamed to `from_user` (`message.from_user`) to avoid conflict with Python's `from` keyword. Directly accessing `message.from` will raise an `AttributeError`.
  Fix: Always use `message.from_user` to access information about the user who sent the message.

Install

• pip install pyTelegramBotAPI Install stable version

Imports

• TeleBot

  import telebot
  bot = telebot.TeleBot(TOKEN)

  The primary class for synchronous bots is imported via 'import telebot'.
• AsyncTeleBot

  from telebot.async_telebot import AsyncTeleBot
  bot = AsyncTeleBot(TOKEN)

  The asynchronous bot class requires a specific import path from 'telebot.async_telebot'.
• types

  from telebot import types

  Commonly imported directly for convenience, though 'telebot.types' also works.

Quickstart

This quickstart sets up a basic synchronous 'EchoBot' that replies to /start, /help, and any other text message by echoing the input. Ensure you replace 'YOUR_BOT_TOKEN_HERE' or set the `TELEGRAM_BOT_TOKEN` environment variable with the token obtained from @BotFather. The bot uses `infinity_polling()` to continuously check for new messages.

import os
import telebot

API_TOKEN = os.environ.get('TELEGRAM_BOT_TOKEN', 'YOUR_BOT_TOKEN_HERE')

if not API_TOKEN or API_TOKEN == 'YOUR_BOT_TOKEN_HERE':
    print("Warning: TELEGRAM_BOT_TOKEN environment variable not set or placeholder used. \n"\
          "Please obtain a token from @BotFather on Telegram and set it.")
    exit(1)

bot = telebot.TeleBot(API_TOKEN)

@bot.message_handler(commands=['start', 'help'])
def send_welcome(message):
    bot.reply_to(message, "Hi there, I am an EchoBot. I will echo your messages.")

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

print("Bot started polling...")
bot.infinity_polling()