Telebot Python: как начать писать Telegram-бота

Telebot — это привычное название работы с библиотекой pyTelegramBotAPI. Она удобна для первого Telegram-бота на Python: синхронный код, простые декораторы, быстрый запуск через polling

Для старта нужно создать бота в BotFather, получить токен, установить библиотеку, написать обработчик команды /start и запустить скрипт

Установка

pip install pyTelegramBotAPI

В коде библиотека импортируется как telebot

import telebot

Если импорт не работает, проверьте, что устанавливаете пакет в ту же среду Python, из которой запускаете скрипт

Минимальный бот

import telebot

bot = telebot.TeleBot('PASTE_TOKEN_HERE')

@bot.message_handler(commands=['start'])
def start(message):
    bot.send_message(message.chat.id, 'Привет, я работаю')

bot.infinity_polling()

Замените PASTE_TOKEN_HERE на токен от BotFather, запустите файл и отправьте боту команду /start

Если все настроено правильно, бот ответит сообщением Привет, я работаю

Токен через переменную окружения

Токен нельзя публиковать в статье, репозитории или скриншоте. Лучше читать его из переменной окружения

import os
import telebot

token = os.getenv('TELEGRAM_BOT_TOKEN')

if not token:
    raise RuntimeError('Не задана переменная TELEGRAM_BOT_TOKEN')

bot = telebot.TeleBot(token)

@bot.message_handler(commands=['start'])
def start(message):
    bot.send_message(message.chat.id, 'Бот запущен')

bot.infinity_polling()

Так скрипт сразу остановится с понятной ошибкой, если токен забыли передать

По этой теме полезно отдельно посмотреть Составьте еженедельное расписание занятий, чтобы расширить контекст и сравнить подходы

По этой теме полезно отдельно посмотреть Аннотации типов для декораторов в Python, чтобы расширить контекст и сравнить подходы

Команда help

Добавим вторую команду, чтобы пользователь понимал, что умеет бот

@bot.message_handler(commands=['help'])
def help_command(message):
    text = (
        'Команды:\\n'
        '/start — запустить бота\\n'
        '/help — показать помощь'
    )
    bot.send_message(message.chat.id, text)

Этот обработчик нужно разместить до bot.infinity_polling()

Ответ на обычный текст

Обработчик текста можно сделать через content_types

@bot.message_handler(content_types=['text'])
def echo(message):
    bot.send_message(message.chat.id, f'Вы написали: {message.text}')

Если пользователь напишет любое сообщение, бот повторит его с короткой подписью

Для учебного бота этого достаточно. Для реального помощника лучше заранее определить команды и не превращать все сообщения в бесконечное эхо

Кнопки через ReplyKeyboardMarkup

Простая клавиатура помогает не заставлять пользователя помнить команды

import telebot
from telebot import types

bot = telebot.TeleBot('PASTE_TOKEN_HERE')

@bot.message_handler(commands=['start'])
def start(message):
    keyboard = types.ReplyKeyboardMarkup(resize_keyboard=True)
    keyboard.add('Прайс', 'Контакты')

    bot.send_message(
        message.chat.id,
        'Выберите раздел',
        reply_markup=keyboard
    )

@bot.message_handler(content_types=['text'])
def handle_text(message):
    if message.text == 'Прайс':
        bot.send_message(message.chat.id, 'Базовый тариф — 5000 рублей')
    elif message.text == 'Контакты':
        bot.send_message(message.chat.id, 'Напишите нам: hello@example.com')
    else:
        bot.send_message(message.chat.id, 'Выберите кнопку или напишите /help')

bot.infinity_polling()

Это уже полезный шаблон для маленького бота-визитки, учебного помощника или простого меню

Как устроены message и chat.id

В обработчик приходит объект message. В нем есть текст, данные пользователя, чат и другие поля

Чаще всего на старте нужны два значения:

message.text
message.chat.id

message.text — то, что написал пользователь

message.chat.id — куда отправлять ответ

Если отправить сообщение не в тот chat.id, бот не ответит пользователю, который написал команду

Polling и webhook

Для первого запуска используйте bot.infinity_polling(). Скрипт сам будет опрашивать Telegram и получать новые сообщения

Для продакшена иногда выбирают webhook: Telegram сам отправляет обновления на ваш сервер. Но webhook требует публичный HTTPS-адрес и больше инфраструктуры

Поэтому нормальный путь такой: сначала polling на локальной машине, потом аккуратный перенос на сервер, затем webhook только при реальной необходимости

Частые ошибки

• вставить неправильный токен
• случайно опубликовать токен в коде
• запустить два процесса одного и того же бота
• забыть, что обработчики должны быть объявлены до infinity_polling()
• назвать файл telebot.py и сломать импорт библиотеки
• ожидать ответ от бота, которому пользователь еще не написал первым
• ловить все текстовые сообщения раньше более точных обработчиков

Практика

Соберите маленького бота за четыре шага

1. Команда /start приветствует пользователя
2. Команда /help показывает список возможностей
3. Кнопки Прайс и Контакты выводят разные ответы
4. Токен читается из переменной окружения

После этого добавьте одну полезную функцию под свою задачу: чек-лист, список услуг, подборку ссылок, напоминание или мини-опрос

Чтобы начать писать Telegram-бота через telebot, установите pyTelegramBotAPI, создайте TeleBot, добавьте обработчики через @bot.message_handler и запустите bot.infinity_polling()

Для первого проекта telebot хорош тем, что дает понятный синхронный код. Для больших ботов с высокой нагрузкой можно позже смотреть в сторону асинхронных фреймворков и webhook