5 ошибок при создании первого Telegram-бота, которые стоили мне кучи времени. И еще 4 — про Mini Apps

Привет. Если вы, как и я когда-то, решили написать своего первого Telegram-бота, то наверняка знакомы с этим чувством: кажется, что все просто, а потом натыкаешься на десяток неочевидных проблем.

Я хочу поделиться списком граблей, на которые наступил лично. Это не теория, а выводы из практики, которые, надеюсь, сэкономят вам время и нервы.

Мой первый бот должен был стать швейцарским ножом: парсить новости, интегрироваться с CRM, проводить сложные опросы. Я потратил недели, пытаясь связать все это в монструозный, но полурабочий прототип.

Как надо было: Начинать с MVP (минимально жизнеспособного продукта). Выбрать одну ключевую функцию и довести ее до идеала. Если это новостной бот — пусть он для начала просто парсит один сайт и присылает статьи. Отладили, протестировали, получили фидбэк — можно добавлять новые фичи. Это спасает от выгорания и позволяет не утонуть в сложности проекта.

Мой первый коммит выглядел примерно так: bot = Bot(token="12345:ABC..."). Токен, ключи API, все тексты сообщений и названия кнопок были прямо в коде. Удобно ровно до первого изменения или попытки выкатить бота на сервер.

Как надо было:

Токены и ключи API — выносить в переменные окружения (.env файл). Это стандарт безопасности и позволяет иметь разные конфиги для локальной разработки и продакшена.
Тексты и кнопки — в отдельный конфигурационный файл (например, texts.yaml или messages.json). Это позволяет менять контент, не переписывая код, и закладывает основу для будущей локализации.

Я был так увлечен возможностями FSM (машины состояний), что построил многоуровневый диалог с кучей ветвлений. На схеме все выглядело логично, но реальные пользователи терялись: они не понимали, где находятся, как отменить действие или вернуться в главное меню.

Как надо было:

Проектировать User Flow. Перед кодом нарисовать схему диалога в Miro или Figma. Сразу видны тупики и узкие места.
Давать «аварийный выход». У пользователя всегда должна быть кнопка «Отмена» или команда /start, которая сбрасывает его состояние и возвращает в главное меню.
Держать в курсе. После каждого шага коротко подтверждать действие и объяснять, что делать дальше.

Когда ботом начали пользоваться первые 10–20 человек, он начал «зависать». Проблема была в том, что я не учел лимиты Telegram Bot API. Мой бот при попытке отправить 30 сообщений в секунду ловил ошибку 429: Too Many Requests и падал.

Как надо было:

Прочитать документацию по лимитам. Это первое, что нужно сделать.
Оборачивать код в try...except. Бот не должен падать от каждой предсказуемой ошибки (chat not found, bot was blocked by the user). Он должен логировать ее и продолжать работать.
Использовать очередь. Для массовых рассылок сообщения нужно ставить в очередь (например, через Celery или asyncio.Queue) и отправлять их с задержкой, чтобы не превысить лимиты.

Я тестировал бота сам и просил друзей-разработчиков. Все нажимали на правильные кнопки. Но первые же реальные пользователи начали делать все «не так»: отправлять стикеры вместо текста, вводить номер телефона с пробелами, спамить командами. Бот ломался на каждом шагу.

Как надо было:

Привлекать не-айтишников. Лучшие тестировщики — люди, далекие от разработки. Их поведение непредсказуемо, и они найдут самые неочевидные баги.
Стресс-тесты. Специально пытаться «сломать» бота: отправлять файлы, когда он ждет текст, нажимать кнопки в неправильном порядке.

Окей, с ботом разобрались. Но как только вы начинаете делать Mini App, появляются новые, более специфические грабли.

Думать, что единственный путь в Mini App — это кнопка в чате с ботом, значит терять 90% аудитории.

Как надо было: Использовать прямые ссылки вида t.me/your_bot/app_name. Их можно размещать на сайтах, в соцсетях, в QR-кодах. А с помощью параметра startapp (?startapp=promo10) можно передавать в приложение контекст: например, открыть нужный товар или применить промокод. Это маст-хэв для маркетинга.

Если у пользователя темная тема, а ваш Mini App открывается слепяще-белым — это плохой тон.

Как надо было: Адаптировать UI. Telegram Web Apps API передает вашему приложению готовые CSS-переменные (--tg-theme-bg-color, --tg-theme-text-color и т.д.). Используйте их в своем CSS, чтобы приложение выглядело нативно в любой теме.

Пользователь пообщался с ботом, закрыл его, а через неделю забыл, как запустить ваш Mini App. Ему придется долго скроллить историю чата.

Как надо было: Добавить кнопку запуска в меню команд бота через @BotFather. Команда /app (или любая другая) всегда будет видна пользователю при вводе /. Еще лучше — добавить кнопку в меню вложений («скрепка»), это тоже настраивается в @BotFather.

Это самая серьезная техническая ошибка. При запуске Mini App получает от Telegram данные о пользователе (initData). Многие новички просто берут эти данные и отправляют на свой бэкенд, считая их правдивыми. Но все, что приходит с клиента, можно подделать.

Как надо было: Валидировать initData на бэкенде — обязательно.Telegram для этого предоставляет криптографический механизм. Вместе с данными приходит hash. Ваш бэкенд должен сформировать строку для проверки из всех остальных полученных полей, посчитать от нее HMAC-SHA-256 (используя токен бота в качестве секрета) и сравнить с hash от клиента. Если они не совпадают — это попытка подделки запроса. Без этой проверки любой может отправить на ваш сервер запрос от имени любого пользователя Telegram.

Создание даже простого бота — это полноценная разработка продукта в миниатюре. Эти ошибки научили меня, что хороший бот — это не только работающий код, но и продуманная архитектура, UX и отказоустойчивость.

Надеюсь, мой опыт был полезен. А на какие грабли наступали вы при разработке ботов? Делитесь в комментариях.

Мой телеграм: