Создать бота в Telegram можно через @BotFather, но регистрация — только первый шаг. Рабочий бот состоит из сценария, обработчика обновлений, хранилища состояния и безопасной публикации. Ниже — практическая учебная схема: от постановки задачи и получения токена до выбора между long polling и webhook, тестирования и запуска.
Какие задачи решает Telegram-бот
Бот принимает сообщения и события, сопоставляет их со сценарием и возвращает ответ. Он может собрать заявку, показать каталог, провести пользователя по анкете, отправить уведомление оператору или вызвать внешний сервис. Бот не заменяет процесс: если нет правил обработки заявки, одна регистрация в @BotFather не создаст полезный продукт.
Начните с одного маршрута. Учебный пример: пользователь отправляет /start, выбирает «Получить консультацию», вводит вопрос, а бот сохраняет его и показывает номер обращения. На каждом шаге определены вход, проверка, ответ и переход. Команда /cancel возвращает пользователя в начальное состояние. Это проще тестировать, чем сразу строить универсальный «умный» диалог.
- цель: какое действие должно завершиться;
- аудитория: кто пишет и какие данные допустимы;
- канал результата: бот, оператор, CRM или почта;
- исключения: отмена, неверный формат, повторное сообщение;
- метрика: завершённая заявка, а не количество ответов.
Регистрация через @BotFather
Откройте официальный аккаунт @BotFather и используйте команду /newbot. Он попросит отображаемое имя и username, затем выдаст токен Bot API. В документации Telegram указано, что username должен соответствовать правилам и обычно оканчиваться на bot; после выбора его нельзя рассчитывать легко переименовать, поэтому проверьте вариант заранее.
Токен — это секрет, фактически ключ управления ботом. Не вставляйте его в публичный репозиторий, HTML, скриншоты, тикеты и логи. Храните его в секретах окружения. Если токен стал доступен постороннему, отзовите его через @BotFather и обновите конфигурацию приложения. Команды /setdescription, /setabouttext и /setcommands помогают оформить профиль и подсказки, но не заменяют обработчик.
| Элемент | Назначение | Где хранить |
|---|---|---|
| Токен | Авторизация API | Секрет окружения |
| Username | Поиск и ссылка | Конфигурация приложения |
| Команды | Подсказки пользователю | BotFather и код |
| Состояние | Текущий шаг диалога | База или временное хранилище |
Как бот получает обновления
Bot API предоставляет два взаимоисключающих способа получения обновлений: getUpdates и webhook. Long polling подходит для локальной разработки и простого сервера: приложение периодически вызывает API с параметром timeout, получает массив обновлений и передаёт их обработчику. После успешной обработки нужно двигать offset, чтобы не получать подтверждённые события снова.
Webhook подходит для постоянно доступного приложения. Telegram отправляет JSON POST на HTTPS-адрес, когда появляется обновление. Если сервер отвечает неуспешным статусом, доставка может повторяться, поэтому обработчик должен быть идемпотентным. Установите секретный заголовок webhook и проверяйте его. Пока webhook настроен, getUpdates не используется; при переходе удалите webhook по правилам API.
| Критерий | Long polling | Webhook |
|---|---|---|
| Старт | Проще локально | Нужен публичный HTTPS |
| Доставка | Приложение забирает события | Telegram отправляет события |
| Контроль | Offset | Секретный заголовок и ответ сервера |
| Сценарий | Прототип и небольшой бот | Постоянная эксплуатация |
Минимальный обработчик сценария
Разделите транспорт и бизнес-логику. Транспорт получает обновление и передаёт его функции маршрутизации. Маршрутизатор определяет команду, callback-кнопку или обычный текст. Сервис сценария проверяет состояние пользователя и формирует действие. Отдельный клиент Telegram вызывает sendMessage или другой метод API. Такое разделение позволяет менять long polling на webhook без переписывания сценария.
Для каждого сообщения учитывайте, что в обновлении может отсутствовать обычный текст: пользователь может прислать фото, нажатие inline-кнопки или служебное событие. Проверяйте тип объекта перед чтением полей. Не считайте наличие message гарантированным и не помещайте в ответ необработанные данные пользователя без экранирования.
Состояние храните по идентификатору чата или пользователя в зависимости от сценария. Если диалог коллективный, состояние по user ID не смешивайте с состоянием чата. Для простого прототипа подойдёт небольшое хранилище, для рабочей нагрузки нужны TTL, блокировка повторной обработки и резервное копирование. Персональные данные храните только в объёме, необходимом для задачи.
Кнопки, команды и валидация
Команды хороши для явных действий: старт, помощь, отмена. Кнопки сокращают число ошибок в выборе. После callback-события бот должен быстро подтвердить его и только затем выполнять более долгую операцию, если это требуется сценарием. Текстовые поля валидируйте на границе: пустое значение, длина, формат даты или телефона должны приводить к понятной подсказке, а не к исключению в приложении.
Не обещайте пользователю действие до подтверждения внешнего сервиса. Если заявка записана в CRM, покажите номер ответа; если сервис недоступен — сообщите, что запрос не завершён, и предложите повторить. Для повторной доставки используйте ключ события или собственной заявки. Это защищает от дублей при повторе webhook.
Интеграции и права доступа
Подключайте внешние системы через отдельный сервисный слой. Бот не должен иметь доступ ко всей базе, если ему нужны только создание заявки и чтение статуса. Ограничьте права токена, добавьте тайм-ауты и журналируйте технический результат без секретов и лишних персональных данных. Для долгих операций ставьте задачу в очередь и сразу отвечайте пользователю о принятии запроса.
Если бот добавлен в группу, учитывайте режим приватности и фактические права. По умолчанию бот может видеть не все сообщения группы. Это не ошибка обработчика и не повод просить лишние разрешения. Сначала определите, действительно ли сценарию нужны все сообщения. Для уведомлений в канал или группу заранее проверьте, может ли бот отправлять сообщения в целевой чат.
Тестирование перед запуском
Сделайте таблицу сценариев: команда, нормальный ввод, пустой ввод, неверный ввод, повтор, отмена, недоступный внешний сервис и повторное обновление. Проверьте, что секреты не появляются в логах, а ошибка одной заявки не останавливает обработку следующих. Для webhook отдельно проверьте HTTPS, секретный заголовок и ответ в допустимом диапазоне 2xx.
- создайте тестового пользователя и не используйте реальные персональные данные;
- проверьте /start, /help и /cancel;
- отправьте два одинаковых сообщения и убедитесь, что операция не дублируется;
- перезапустите приложение между шагами и проверьте восстановление состояния;
- искусственно вызовите ошибку API и убедитесь, что пользователь получает понятный статус;
- проверьте, что отзыв токена останавливает доступ.
Типичные ошибки при создании бота
Частая ошибка — положить токен в файл конфигурации, который попадает в Git. Вторая — использовать одновременно webhook и getUpdates. Третья — считать успешным любой HTTP-ответ без проверки поля ok в JSON Bot API. Четвёртая — не учитывать повторную доставку. Пятая — хранить состояние только в памяти, а затем терять незавершённые диалоги при перезапуске.
Не задавайте в статье или документации неподтверждённые лимиты как вечные значения: они меняются. Сверяйте ограничения с актуальным справочником Bot API. Не используйте токен из примеров в рабочем окружении. Учебный код должен явно показывать, где находится секрет, но не содержать настоящий секрет.
Запуск и дальнейшее обслуживание
Перед запуском зафиксируйте версию приложения, переменные окружения, способ доставки обновлений, команды и план отката. Настройте мониторинг ошибок, длины очереди, времени ответа и доли незавершённых сценариев. Периодически проверяйте журнал webhook или ошибки polling. Обновления Telegram и внешних сервисов могут менять поведение, поэтому раз в период запускайте набор регрессионных сценариев.
Готовый бот — это не только ссылка на username. Он безопасно принимает обновления, понимает состояние пользователя, не создаёт дубли, сообщает правду о результате и позволяет владельцу отозвать доступ. Начинайте с одного измеримого сценария, проверяйте его на тестовых данных и расширяйте только после того, как журнал и обработка ошибок стали понятными.
Полезно вести журнал решений по сценарию: какие команды поддерживаются, какие данные удаляются, когда заявка передаётся человеку и что происходит при отсутствии ответа оператора. Такой документ сокращает расхождение между кодом, текстами кнопок и ожиданиями команды. При изменении процесса сначала обновите схему переходов, затем код и тесты.
Для небольшого проекта достаточно простого запуска, но требования к безопасности остаются теми же. Разделяйте тестовый и рабочий токены, ограничивайте доступ к окружению, обновляйте зависимости и заранее определяйте, кто может остановить бота. Если бот обрабатывает заявки клиентов, добавьте понятное уведомление о том, какие сведения он получает и зачем они нужны.
Перед расширением сценария измерьте, где пользователи прерывают диалог. Если многие нажимают отмену после запроса контакта, возможно, проблема не в кнопке, а в слишком раннем сборе данных. Перенесите необязательное поле ближе к моменту, когда понятна ценность действия. Технические метрики полезны вместе с редакционным просмотром реальных обезличенных диалогов.
Продумайте повторный вход. Пользователь может открыть бот через несколько часов, отправить /start заново или нажать старую кнопку. Сценарий должен объяснить, что произойдёт с предыдущей заявкой, и не молча затереть важные данные. Для устаревших callback-кнопок возвращайте сообщение о том, что меню нужно открыть заново. Это лучше, чем выполнять действие из старого состояния.
Для команды поддержки добавьте техническую трассировку: идентификатор обновления, идентификатор сценария, длительность операции и результат внешнего вызова. Не записывайте полный текст сообщения, если он не нужен для диагностики. Маскируйте телефон, почту и другие персональные данные. Ограничьте срок хранения логов и доступ к ним теми сотрудниками, которым он нужен.
При выпуске новой версии используйте постепенное включение. Сначала проверьте команды на тестовом боте, затем включите один сценарий для небольшой группы и сравните ошибки с предыдущей версией. Храните возможность быстро вернуть прежнюю конфигурацию. Такой подход особенно важен, когда бот связан с оплатой, заявками или уведомлениями: цена незаметной ошибки выше цены дополнительной проверки.
Перед передачей проекта владельцу подготовьте короткую эксплуатационную памятку: username бота, способ получения обновлений, расположение секретов без самих значений, команды, контакт ответственного и процедуру экстренной остановки. Памятка не должна содержать токен. Она помогает восстановить работу после сбоя и не превращает знания о боте в зависимость от одного разработчика.
Проверяйте памятку после каждого заметного изменения API или сценария. Устаревшая инструкция опаснее отсутствующей: она создаёт ложную уверенность при инциденте. Держите рядом ссылку на официальный справочник Telegram и дату последней проверки, а спорные или изменчивые ограничения не превращайте в обещания пользователю.
Не забывайте о человеческом выходе из автоматизации. Пользователь должен понимать, как отменить действие, повторить запрос или связаться с оператором, если бот не помог. Это снижает раздражение и даёт команде понятный маршрут для сложных случаев, которые нельзя надёжно решить набором команд.