Введение в Telegram-боты: регистрация, получение токена, основные понятия
Чтобы по итогу нашего хендбука у вас получился свой небольшой проект — давайте рассмотрим, как создавать телеграм-боты. И в конце вы сможете делать свой!
Telegram-бот — это специальное автоматизированное приложение, которое работает внутри мессенджера Telegram. Его задача — принимать, обрабатывать и отправлять сообщения пользователям, выполнять различные действия (отправка информации, автоматизация чата, интеграция с сайтами и CRM и т. д.). Боты используют программный интерфейс (API) для взаимодействия с Telegram.
API Telegram Bot — это набор инструментов (методов), с помощью которых можно управлять ботом, читать сообщения, отвечать пользователям, отправлять медиа и выполнять другие действия.
Токен — это уникальный длинный ключ (строка символов), выдаваемый Telegram для каждого бота. По сути, это аналог пароля, с его помощью бот получает доступ к Telegram API.
Для регистрации бота нужен BotFather — официальный сервисный бот Telegram для создания и управления другими ботами.
Найдите его по поиску (имя: @BotFather, прямая ссылка https://t.me/BotFather) и начните диалог с команды /start:
Далее выберите команду /newbot (нажмите на нее). Вам предложат выбрать имя бота (любое красивое название, например «Бот для задач»):
Далее вас попросят ввести username (уникальный идентификатор, который обязательно должен оканчиваться на «bot», например: my 123_bot):
После этого BotFather пришлёт вам сообщение с токеном (на нашем скриншоте токе замазан):
Это — ваш ключ для работы с Telegram Bot API. Скопируйте и сохраните его.
Теперь мы можем создать свой первый бот!
Для новичков удобнее всего использовать готовые библиотеки: например, pytelegrambotapi. Установим нужную библиотеку:
!pip install pytelegrambotapi
Теперь мы можем запрограммировать наш первый бот.
Для этого нужно выполнить следующие шаги:
импортировать нужную библиотеку
создать экзамепляр телеграм-бота (т.е. именно наш бот) на основе токена
придумать, какие команды у нас будут (пока оставим только команду start)
прописать, что будет происходить при вызове команды
Давайте разберемся, что происходит в коде выше по маленьким кусочкам.
bot = telebot.TeleBot('ВАШ_ТОКЕН')
Здесь создается экземпляр класса TeleBot, т. е. именно ваш бот, который позволяет реализовывать различные функции и обмениваться сообщениями.
Параметр 'ВАШ_ТОКЕН' — это API токен, который вы получаете от BotFather при создании бота в Telegram.
Далее идет обработчик команд:
@bot.message_handler(commands=['start'])
def start_message(message):
bot.send_message(message.chat.id, "Привет! Я - ваш бот.")
Декоратор@bot.message_handler — это специальный механизм, который позволяет задать фильтр для далее идущей функции. То есть, он может ограничивать действие функций и вызывать их только при вызове каких-то команд или, например, при отправлении боту контента определенного формата. Параметр commands=['start'] указывает, что следом идущая функция должна вызываться строго команды /start. Команды в Telegram всегда начинаются с символа /. Вы можете указать несколько команд: commands=['start', 'help']
Далее идет уже сама функция:
def start_message(message):
bot.send_message(message.chat.id, "Привет! Я - ваш бот.")
Она может иметь произвольное имя, но должна иметь только один параметр — message. Параметр message содержит всю информацию о полученном сообщении, включая:
message.chat.id — идентификатор чата
message.text — текст сообщения
message.from_user — информация о пользователе
И много других полезных свойств
Метод send_message отправляет текстовое сообщение пользователю. Принимает два основных параметра:
message.chat.id — идентификатор чата, куда отправить сообщение
«Привет! Я — ваш бот.» — текст сообщения
Команды написаны, теперь можем запустить бот:
bot.polling()
Метод polling () запускает процесс длительного опроса, при котором бот периодически отправляет запросы на серверы Telegram для получения новых сообщений.
Как это работает:
1. Бот отправляет запрос на сервер Telegram с вопросом «есть ли новые сообщения?» 2. Если сообщений нет, сервер удерживает соединение открытым до тех пор, пока не придет новое сообщение или не истечет время ожидания 3. Когда приходит новое сообщение, сервер сразу же отправляет его боту 4. Бот обрабатывает сообщение и немедленно отправляет новый запрос
Таким образом, бот работает бесконечно!
В нашем боте мы с помощью специального декоратора просили функцию реагировать только на команду start. Такие декораторы называются хендлерами.
Хендлеры (обработчики) — это специальные функции, которые запускаются, когда ваш бот получает сообщения или события от пользователей в Telegram. Когда кто-то пишет боту или что-то с ним делает, хендлер «ловит» это сообщение и выполняет запрограммированное действие — например, отвечает текстом или сохраняет фото.
Хендлеры создаются с помощью специального декоратора — строки с @bot.message_handler (…). В скобках указываются условия, при которых будет срабатывать именно эта функция.
Например, чтобы бот отвечал на любые входящие текстовые сообщения, надо написать такой код:
@bot.message_handler(content_types=['text']) # Указываем, что реагируем на текст
def echo(message):
bot.send_message(message.chat.id, f'Вы написали: {message.text}')
content_types=['text'] говорит боту, что эта функция обрабатывает только текст.
Внутри функции echo бот отправляет сообщение обратно с тем же текстом, который написал пользователь.
Так бот будет повторять всё, что ему напишут (будет работать как эхо).
Вместо текста бот может получать фото, аудио, видео, документы и другие типы сообщений. Чтобы реагировать на них, нужно указать нужный тип в content_types при создании хендлера.
Например, чтобы обрабатывать только фотографии и сохранять их на компьютер, пишут так:
@bot.message_handler(content_types=['photo']) # ловим фото
def handle_photo(message):
photo = message.photo[-1] # берем самое лучшее качество
file_id = photo.file_id # получаем уникальный идентификатор фото
# скачиваем фото с серверов Telegram
file_info = bot.get_file(file_id)
downloaded_file = bot.download_file(file_info.file_path)
# сохраняем фото в файл на компьютере с именем "photo.jpg"
with open("photo.jpg", "wb") as new_file:
new_file.write(downloaded_file)
# отправляем сообщение пользователю, что фото сохранено
bot.send_message(message.chat.id, "Фото сохранено!")
Telegram присылает сообщения не только при обычных текстах, но и при событиях, например, если в группу добавляется новый человек. Такие события тоже можно ловить хендлерами.
Вот пример, который приветствует каждого нового участника в чате:
@bot.message_handler(content_types=['new_chat_members'])
def new_member_handler(message):
for new_member in message.new_chat_members:
bot.send_message(message.chat.id, f"Добро пожаловать, {new_member.first_name}!")
content_types=['new_chat_members'] — бот смотрит только на сообщения с новыми участниками.
Для каждого нового пользователя отправляется приветствие.
Можно создать хендлер, который запускается не по конкретному типу, а по условию, например, если в сообщении есть слово «привет» (в любом регистре):
@bot.message_handler(func=lambda message: 'привет' in message.text.lower())
def greet_handler(message):
bot.send_message(message.chat.id, f"Привет, {message.from_user.first_name}!")
Здесь func=… — это функция, которая проверяет условие и возвращает True или False. Если True, бот отвечает.
Можно добавить клавиатуру с кнопками, чтобы пользователю было удобнее и интереснее общаться с ботом.
Это расширяет возможности бота, позволяя делать его мультимедийным и интерактивным.
В завершение нашего хендбука давайте напишем телеграм-бот, агрегируя полученные знания!
Мы создадим бот для форматирования текстов, который помогает быстро обрабатывать текст прямо в чате без отдельного приложения или сайтов. Что он будет уметь:
Преобразовывать текст в верхний или нижний регистр (удобно для правил оформления).
Убирать лишние пробелы и переносы строк.
Заменять буквы «ё» на «е» (или наоборот) по запросу.
Считать количество символов и слов в тексте.
Может сразу выдать результат обратным сообщением.
Ниже расположен код бота, а еще ниже подробные пояснения к нему:
import telebot
TOKEN = "ВАШ_ТОКЕН_ОТ_БОТА"
bot = telebot.TeleBot(TOKEN)
@bot.message_handler(commands=['start'])
def start_message(message):
bot.send_message(message.chat.id,
"Привет! Я бот для форматирования текста.\n"
"Используй команды:\n"
"/upper [текст] — в верхний регистр\n"
"/lower [текст] — в нижний регистр\n"
"/clean [текст] — убрать лишние пробелы\n"
"/count [текст] — посчитать слова и символы\n\n"
"Пример: /upper Привет мир!"
)
def extract_text(message):
parts = message.text.split(maxsplit=1)
if len(parts) > 1:
return parts[1]
else:
return None
@bot.message_handler(commands=['upper'])
def to_upper(message):
text = extract_text(message)
if text:
bot.send_message(message.chat.id, text.upper())
else:
bot.send_message(message.chat.id, "Пожалуйста, добавьте текст после команды.")
@bot.message_handler(commands=['lower'])
def to_lower(message):
text = extract_text(message)
if text:
bot.send_message(message.chat.id, text.lower())
else:
bot.send_message(message.chat.id, "Пожалуйста, добавьте текст после команды.")
@bot.message_handler(commands=['clean'])
def clean_text(message):
text = extract_text(message)
if text:
cleaned = " ".join(text.split())
bot.send_message(message.chat.id, cleaned)
else:
bot.send_message(message.chat.id, "Пожалуйста, добавьте текст после команды.")
@bot.message_handler(commands=['count'])
def count_text(message):
text = extract_text(message)
if text:
words = len(text.split())
chars = len(text)
bot.send_message(message.chat.id, f"Слов: {words}\nСимволов: {chars}")
else:
bot.send_message(message.chat.id, "Пожалуйста, добавьте текст после команды.")
bot.polling()
Первоначально мы импортируем библиотеку:
import telebot
Этим мы подключаем готовый набор инструментов для создания телеграм-бота — библиотеку telebot.
Здесь TOKEN — это уникальный ключ, который вы получаете у @BotFather в Telegram. Он нужен, чтобы бот работал именно с вашим аккаунтом. А код telebot.TeleBot (TOKEN) создаёт объект бота, через который мы будем принимать команды и отправлять ответы.
Далее идет реакция бота на команду 'start':
@bot.message_handler(commands=['start'])
def start_message(message):
bot.send_message(message.chat.id, "Привет! Я бот для форматирования текста..." )
@bot.message_handler (commands=['start']) — это декоратор. Он говорит: «Эта функция start_message должна работать, когда пользователь пишет команду /start.»
message — объект, который содержит все данные от пользователя (его ID, текст и другое).
bot.send_message (message.chat.id, …) — отправляет ответ в тот же чат, откуда пришло сообщение.
Далее идет вспомогательная функция для извлечения текста после команды:
def extract_text(message):
parts = message.text.split(maxsplit=1)
if len(parts) > 1:
return parts[1]
else:
return None
message.text — полный текст, который отправил пользователь, например: /upper Привет
split (maxsplit=1) разделяет текст на две части: команду и остальной текст.
Функция возвращает то, что после команды, или None, если текста нет.
Далее в коде идет обработка команд /upper, /lower, /clean, /count
Для каждой команды есть функция, которая:
получает текст после команды,
проверяет, что текст есть,
и обрабатывает его (переводит в верхний регистр — upper (), в нижний — lower (), удаляет лишние пробелы, считает слова и символы).
Пример, функция для команды /upper:
@bot.message_handler(commands=['upper'])
def to_upper(message):
text = extract_text(message)
if text:
bot.send_message(message.chat.id, text.upper())
else:
bot.send_message(message.chat.id, "Пожалуйста, добавьте текст после команды.")
И в конце идет запуск бота:
bot.polling()
Эта команда говорит боту «начинай работать». Он постоянно проверяет, пришли ли новые сообщения, и запускает соответствующие функции.
Как это работает вместе?
Пользователь приходит и пишет, например, /upper привет
Telegram отправляет сообщение вашему боту
Декоратор видит, что это команда /upper, и запускает функцию to_upper
Функция извлекает текст «привет», переводит его в верхний регистр и отправляет обратно
Пользователь видит сообщение «ПРИВЕТ»
Так работает весь бот — по аналогии со всеми командами.
Итак, вы дошли до самого конца бота нашего хендбука! Узнать про все основы языка, а также научились реализовывать телеграм-боты. Надеемся, что вы сможете применить свои знания на практике и развиваться в программировании дальше!