Телеграм-боты — это специальные программы, которые работают внутри мессенджера Telegram. Они взаимодействуют с пользователями через привычный чат и могут реагировать на команды, отвечать на вопросы, отправлять уведомления, обрабатывать платежи, управлять контентом и автоматизировать множество других рутинных задач.
Все боты работают через Telegram Bot API — официальный HTTP-интерфейс, который связывает программу с серверами Telegram. В статье мы разберем, как устроено такое взаимодействие, а затем создадим бота для хранения и организации промптов к нейросетям.
Что нужно знать о Telegram Bot API перед первым созданием бота
Telegram Bot API работает по тому же принципу, что и обычные обращения к сайтам: программа отправляет HTTP-запрос на сервер Telegram, сервер обрабатывает его и возвращает ответ в формате JSON.
Когда пользователь взаимодействует с ботом, весь процесс обмена сообщениями можно разбить на три последовательных этапа:
- Сначала пользователь отправляет боту какое-то сообщение — например, текст «Привет» или команду
/start. - Telegram принимает сообщение и регистрирует его как обновление (update). Если пользователь написал «Привет», Telegram создает JSON-объект с информацией о сообщении.
- Бот анализирует содержимое и отправляет ответ также через Bot API. Однако что отправить, определяет логика программы — это может быть текст, кнопки, изображение, файл, стикер или любой другой тип контента, который поддерживает Telegram.
Ключевая часть этого механизма — способ получения обновлений от Telegram. Существует два основных метода: long polling и webhook.
При long polling бот сам регулярно обращается к API и спрашивает, есть ли новые события. Этот режим подходит для локальной разработки и учебных проектов, поскольку не требует собственного сервера с публичным IP-адресом и HTTPS-сертификатом. Вы запускаете скрипт на ноутбуке — и бот работает. Главное, чтобы в процессе разработки устройство оставалось включенным и было подключено к интернету.
Второй способ — webhook: вы настраиваете HTTPS-адрес на сервере, и Telegram отправляет на него каждое новое обновление в режиме реального времени. Этот вариант необходим для продакшн-ботов, которые должны работать круглосуточно, обрабатывать десятки тысяч запросов в сутки и выдавать ответы с минимальной задержкой.
Независимо от способа получения обновлений, Bot API всегда работает с определенными ограничениями. К примеру, бот не может первым начать диалог — пользователь обязательно должен отправить первое сообщение или команду. Telegram также регулирует скорость отправки сообщений, размер файлов и другие параметры. Подробнее об этом и прочих нюансах вы можете прочитать в документации Telegram API.
Регистрируем бота через BotFather и получаем API-токен
Чтобы обращаться к Telegram и управлять ботом, программе нужен уникальный ключ — токен доступа. Токен представляет собой секретную строку, которая используется при каждом запросе к Bot API: он добавляется к URL-адресу и подтверждает, что именно ваша программа имеет право выполнять действия от имени конкретного бота. Без такого токена Telegram просто не примет ни один запрос.
За выдачу токенов в Telegram отвечает официальный бот @BotFather. Откройте мессенджер, найдите его через поиск и запустите. Далее в списке доступных команд выберите самую первую — /newbot:
Далее BotFather попросит вас указать два имени. Первое — публичное имя, которое увидят все пользователи в списке ваших контактов и в шапке чата. Оно может содержать любые символы, пробелы и даже эмодзи — например, «Мой Помощник» или «Prompt Storage».
Второе имя — это обязательный уникальный username, который должен оканчиваться на bot. Кроме того, username должен быть не занятым другими ботами и может состоять только из латинских букв, цифр и подчеркиваний — без пробелов. Если вы укажете уже занятый username, BotFather сообщит об ошибке и попросит выбрать другой.
Дадим нашему боту название My Prompt Library и username — MyPromptLibraryBot. В ответ BotFather пришлет сообщение со сгенерированным уникальным токеном. В этой статье мы намеренно не будем его скрывать и выключим бота сразу после публикации материала. Вам же рекомендуется держать токен в тайне — если кто-то посторонний его получит, он сможет управлять ботом через Bot API.
Например, многие разработчики по неосторожности публикуют токены в открытых репозиториях на GitHub. Чтобы этого избежать, храните все доступы в переменных окружения или конфигурационных файлах, которые исключены из системы контроля версий через .gitignore.
Также в приветственном сообщении от BotFather есть ссылка на созданного бота. Вы можете кликнуть по ней, а затем нажать кнопку СТАРТ или отправить команду /start для первого взаимодействия:
Отправляем первое сообщение через Bot API
После получения токена вы можете проверить, что Telegram распознает бота и соединение с Bot API работает. Для этого используйте метод getMe — он запросит у сервера базовую информацию о боте и подтвердит, что токен действителен, а бот зарегистрирован в системе.
Скопируйте токен и вставьте его в эту ссылку:
https://api.telegram.org/bot<ВАШ_ТОКЕН>/
Затем вставьте полученный URL в браузер. Если все в порядке, Telegram вернет JSON-объект примерно такого вида:
{
"ok": true, // Запрос выполнен успешно
"result": {
"id": 8385116600, // Уникальный ID бота
"is_bot": true, // Подтверждение, что это бот
"first_name": "My Prompt Library", // Публичное имя бота
"username": "MyPromptLibraryBot", // Username бота
"can_join_groups": true, // Может ли бот вступать в группы
"can_read_all_group_messages": false, // Видит только сообщения с упоминанием бота
"supports_inline_queries": false, // Поддерживает ли бот inline-режим
"can_connect_to_business": false, // Может ли бот работать с Telegram Business API
"has_main_web_app": false // Наличие главного веб-приложения
}
}
В документации к Telegram Bot API описано множество подобных методов и для закрепления давайте воспользуемся еще одним.
Для начала отправьте своему боту любое сообщение в чате:
Подставьте токен и откройте строку в браузере:
https://api.telegram.org/bot<ВАШ_ТОКЕН>/getUpdates
В полученном JSON-ответе найдите поле chat, а внутри него — поле id. Это уникальный идентификатор вашего чата с ботом. Скопируйте это число и подставьте его вместе с токеном в следующую строку:
https://api.telegram.org/bot<ТОКЕН>/sendMessage?chat_id=<CHAT_ID>&text=Привет!
Если вы нигде не ошиблись, то увидите в чате ответ от бота:
Вы наверняка обратили внимание, что для отправки простейшего уведомления нам понадобилось несколько последовательных запросов: сначала получить обновления через getUpdates, затем извлечь из ответа идентификатор чата и только после этого отправить сообщение через sendMessage. И чем сложнее будет функционал бота, тем более громоздкой становится работа с чистым API через HTTP-запросы.
Поэтому в реальных проектах практически никто не работает с Bot API напрямую, поскольку это имеет смысл только в специфических случаях. Например, когда необходимо отправить разовое уведомление из внешней системы или написать простой скрипт для мониторинга. Вместо этого разработчики подключают библиотеки, которые берут на себя работу с API и позволяют сосредоточиться на логике приложения.
Выбираем инструменты и проектируем архитектуру бота
Благодаря Telegram Bot API мы можем написать бота практически на любом современном языке программирования — подойдут:
- Python;
- JavaScript (Node.js);
- Go;
- C#;
- Java;
- PHP;
- Ruby и многие другие.
Главное, чтобы язык поддерживал отправку HTTP-запросов и работу с JSON.
В следующем разделе мы создадим хранилище промптов для нейросетей. Пользователь сможет добавлять текстовые шаблоны, присваивать им категории, просматривать список сохраненных промптов, искать нужный по ключевым словам и удалять записи.
Для получения обновлений от Telegram нам подойдет метод long polling. За счет этого подхода бот сможет работать локально на вашем компьютере — его не придется дополнительно разворачивать на удаленном сервере с публичным IP-адресом и настраивать webhook.
Чтобы реализовать описанный функционал, мы будем использовать язык Python и асинхронный фреймворк aiogram. Этот фреймворк упрощает работу с Bot API, автоматически обрабатывает входящие обновления и предоставляет удобные инструменты для создания команд, обработки сообщений и управления состояниями диалога.
Еще перед разработкой мы рекомендуем визуализировать архитектуру вашего бота. Это можно сделать в Obsidian, другом редакторе или просто на листе бумаги. Нарисуйте основные компоненты и потоки данных: продумайте, как пользователь будет взаимодействовать с ботом, какие команды обрабатывать, где хранить данные и как они передаются между модулями. Если в процессе разработки архитектура изменится — это нормально. Главное, чтобы вы сразу увидели полную картину проекта и понимали, как работает каждый ее компонент.
Схема работы нашего бота: сообщение пользователя проходит через Telegram Bot API, попадает в логику бота и обрабатывается вместе с обращениями к хранилищу. Поскольку это учебный проект, архитектура показана укрупненно; в реальных проектах обычно детализируют работу каждого компонента.
Если вы пока не знаете, какие технологии выбрать — воспользуйтесь готовым промптом для любой нейросети. Добавьте в него краткое описание своего бота и при желании прикрепите скриншот архитектуры, чтобы ИИ выдал более точные рекомендации:
Я хочу создать Telegram-бота, но не знаю, какие языки и инструменты выбрать. Мой проект: - Цель бота: [опишите своими словами] - Что бот должен уметь: [краткий список функций] - Где бот будет работать: локально / на сервере / в облаке - Уровень моих знаний: [начинающий / средний / продвинутый] Предложи оптимальный стек: язык программирования, библиотеку для работы с Bot API, хранилище данных и дополнительные инструменты. Объясни, почему предложенный стек оптимален для моего проекта и какой уровень сложности ожидает меня на каждом этапе разработки. Дай пример структуры проекта с описанием назначения каждой папки и файла. Также укажи, какие модули за что отвечают, как они взаимодействуют и какие зависимости потребуются для их работы. Если есть альтернативы — перечисли их с указанием плюсов, минусов и сценариев использования, чтобы я мог сделать осознанный выбор.
Воплощаем идею в рабочего бота
Чтобы не запутаться, в этом разделе мы будем двигаться небольшими шагами — постепенно добавлять новые функции и усложнять проект.
Шаг 1. Настраиваем рабочее окружение
Чтобы начать работу, вам необходимо установить на компьютер Python версии 3.10 или выше. Для проверки введите в терминал команду:
python --version
Следующей командой установите фреймворк aiogram, который будет обрабатывать сообщения и подключаться к Bot API:
pip install aiogram
Дополнительно создадим и активируем виртуальное окружение — оно изолирует зависимости проекта и предотвратит конфликты между библиотеками. Это не обязательно, но мы рекомендуем попробовать. Об этом у нас есть отдельная статья с описанием всех подробностей.
Затем выберите редактор кода и создайте проект. Мы будем работать в Antigravity IDE — редакторе от Google с бесплатными нейросетями. Назовем папку tg-prompt-library и добавим в нее несколько файлов:
- bot.py — файл с кодом бота. Здесь мы создадим обработчики команд, функции для добавления и чтения промптов, а также настроим взаимодействие с API. Мы начнем работать с этим файлом на следующем шаге и будем постепенно его дополнять.
- config.py — модуль для конфигурации. Здесь мы подключим библиотеку python-dotenv для работы с файлами .env, загрузим переменные окружения и получим токен бота. Это обеспечит нам безопасность и позволит не хранить токен напрямую в коде.
- .env — файл, в котором хранится токен от BotFather. Добавьте этот файл в .gitignore, чтобы токен не попал в репозиторий.
- .venv/ — виртуальное окружение с установленными библиотеками, которое также нужно добавить в .gitignore.
Перед написанием кода установим еще одну библиотеку. Она нужна для безопасной работы с токеном через файл .env. Вот команда:
pip install python-dotenv
На этом подготовительная часть закончена. Понимаем, что нюансов много, поэтому структуру проекта вы можете скачать по этой ссылке.
Шаг 2. Создаем минимальную версию бота
На этом этапе мы добавим три базовые команды: /add — будет запускать диалог для сохранения промпта, /list — показывать все сохраненные записи, /get <id> — выводить промпт по его номеру.
Для реализации этого функционала создадим локальное хранилище в формате JSON, где каждый промпт будет сохраняться как отдельная запись с уникальным идентификатором (ID), названием и текстом.
Теперь продумаем диалог с пользователем. Он будет состоять из двух шагов: сначала бот попросит ввести короткое название промпта, затем — сам текст. После сохранения бот автоматически присвоит промпту уникальный номер и сообщит об этом пользователю. Этот номер нужно указать в команде /get <id> для быстрого получения промпта.
Позже мы добавим удобный вывод, категории и страницы управления промптами. Но сейчас важно создать основу проекта и убедиться, что все работает корректно. Скачайте первую версию файла bot.py и добавьте его в проект. Если ваша структура совпадает с той, что мы создали на предыдущих шагах, выполните в терминале команду python bot.py и переходите в Telegram для тестирования первой версии бота.
Запускаем бота в Telegram и добавляем новый промпт:
Проверим команду /list и выведем сохраненный текст промпта:
Теперь, если вы откроете файл prompts.json, то увидите добавленный пост с его id, названием и полным текстом:
Бот работает до тех пор, пока вы не остановите его командой Ctrl+C или не закроете терминал — так работает механизм long polling, который мы разбирали в теории. Пока бот запущен, вы можете отправить ссылку другим пользователям, и у них получится его протестировать. А вот для непрерывной работы бот необходимо размещать на удаленном сервере.
Шаг 3. Добавляем больше функций и завершаем проект
У нас все готово, чтобы собрать полноценного Telegram-бота. Он будет не только сохранять промпты, но и классифицировать их по категориям, искать по ключевым словам, показывать список, открывать текст по ID и удалять ненужные записи. Также бот сможет поддерживать многоуровневую навигацию, inline-кнопки и систему состояний для управления диалогом при добавлении промпта.
Когда вы добавите в проект обновленную версию файла bot.py, то получите бота, в котором почти все действия выполняются кнопками. В коде есть комментарии с описанием основных шагов, которые мы выполнили — так вы сможете подробно разобрать, как и что работает.
Перезапустим бота и посмотрим обновленных интерфейс:
Нажмем на кнопку Добавить промпт, введем название, и бот предложит выбрать одну из категорий:
Добавим текст промпта одним сообщением и готово — бот сохранит запись и вернет нас в главное меню:
Кнопка Мои промпты выводит список всех сохраненных записей. Причем у каждого пункта есть две собственные кнопки — одна удаляет промпт, а другая показывает его полный текст:
На всякий случай мы добавим кнопку Помощь, которая описывает все возможности и команды бота:
Если вы захотите развивать проект дальше, вариантов улучшений очень много. Например, можно добавить редактор сохраненных промптов, реализовать экспорт и импорт базы, внедрить пагинацию для больших списков или настроить webhook для круглосуточной работы на сервере.
Что дальше
Лучше одного собственного бота может быть только два бота. Недавно мы опубликовали подробную инструкцию о разновидностях телеграм-ботов, их оформлении, конструкторах и других нюансах.
В этом же материале мы создали бота, который отправляет случайные комплименты. Проект реализован с помощью библиотеки telebot — альтернативы aiogram. Рекомендуем прочитать и попрактиковаться.
