Запуск Telegram-бота: финальный чек-лист

Запуск бота — момент, когда любые недочёты вылезают на пользователях. Этот чек-лист собран по итогам десятков запусков и закрывает технические, продуктовые и юридические пункты. Прогон занимает 4–6 часов и реально снижает количество инцидентов в первые дни. Идея простая: пройти все блоки до запуска, отметить каждый пункт, зафиксировать ответственного — и только потом переключать webhook на боевой адрес.

Чек-лист устроен по приоритетам. Блокеры (без них запуск откладывается) — первые шесть категорий. Желательное (повышает качество, но не валит запуск) — следующие пять. Бонус (нюансы, которые добиваются после soft-launch) — последние три.

Продукт и контент

База, без которой бот не выглядит профессионально. Часто эти пункты откладывают «на потом» и уходят в продакшн с пустым описанием и аватаркой по умолчанию.

• Имя бота финальное, без _test, _dev, _v2.
• Юзернейм (@your_bot) занят, совпадает с маркетинговыми материалами.
• Аватар — квадратный, минимум 640×640, читается в превью списка чатов.
• Описание (/setdescription) — что делает бот, до 512 символов, без воды.
• About-текст (/setabouttext) — короткое описание для карточки, до 120 символов.
• Команды через setMyCommands — минимум /start, /help, /menu, при необходимости /profile, /orders, /support.
• Локализации команд (setMyCommands с language_code) для всех целевых языков.
• Локализация описания (setMyDescription с language_code).
• Демо-сценарий «первый раз»: онбординг проходит человек вне команды разработки за минуту, без инструкции.
• Все сообщения вычитаны редактором, не разработчиком.
• Тон голоса единый, кнопки короткие (до 20 символов).
• Сценарий ошибки даёт явный выход (/menu, кнопка «Назад», ссылка на поддержку).

BotFather

Конфигурация, которую легко забыть, потому что она настраивается одной командой и больше никто на неё не смотрит.

• Privacy mode включён, если бот в группах и не нужен полный доступ к сообщениям (по умолчанию включён, проверьте /setprivacy).
• Inline mode включён, если бот используется inline; задан placeholder.
• Payment provider привязан (/mybots → Payments): ЮKassa, CloudPayments, Stripe и так далее.
• Domain для Login Widget указан, если используется авторизация через Telegram.
• Mini App URL прописан (/newapp), кнопка меню (/setmenubutton) ведёт на корректный адрес.
• Group/channel admin permissions выставлены минимально необходимыми.
• Bot owner и backup admin — два разных Telegram-аккаунта (защита от потери доступа).

Технические

Боль большинства запусков. Webhook настроен, но getWebhookInfo показывает накопленные ошибки — и никто не смотрел туда последние две недели.

• Webhook настроен через setWebhook, ответ HTTP 200 на тестовый запрос.
• secret_token передан в setWebhook и проверяется на каждом входящем запросе (заголовок X-Telegram-Bot-Api-Secret-Token).
• allowed_updates указан явно (только message, callback_query, pre_checkout_query и тому подобное) — без лишних типов событий.
• getWebhookInfo показывает pending_update_count: 0 и last_error_date: null.
• Healthcheck-эндпоинт /health возвращает HTTP 200 за время менее 100 мс.
• Graceful shutdown: при SIGTERM воркер дорабатывает текущие апдейты до 30 секунд, затем завершается.
• Idempotency на платёжные операции: уникальный индекс на (payment_id, event_type) в БД.
• Idempotency на критичные команды (создание заказа, отправка чека) — повторный вызов не дублирует результат.
• HTTPS-сертификат действующий, автообновление через Let's Encrypt или аналог.
• Webhook отвечает быстрее 1–2 секунд (Telegram повторяет неответившие апдейты).
• Долгие операции вынесены в очередь (NATS, RabbitMQ, Celery, BullMQ).

Безопасность

Без этих пунктов запуск возможен, но риск утечки токена и взлома инфраструктуры — вопрос недель.

• Все секреты в .env.production или secrets manager (Vault, AWS Secrets Manager, Yandex Lockbox), не в git.
• .env* в .gitignore, git log -p .env пустой.
• Bot token ротирован минимум один раз (план ротации задокументирован).
• IP-allowlist Telegram на webhook: разрешены только подсети 149.154.160.0/20 и 91.108.4.0/22 (актуальные диапазоны проверить на core.telegram.org).
• Rate limit включён на уровне приложения (например, 30 запросов в минуту на user_id).
• CAPTCHA на /start если есть скам-риск (массовые регистрации, реферальные злоупотребления).
• secret_token проверяется в каждом входящем webhook-запросе.
• Доступ к серверу по SSH-ключу, без паролей.
• Файрвол открывает только 80, 443 и порт API.
• Mini App проверяет initData через HMAC по серверному коду.
• Логи не содержат токенов, паролей, телефонов в открытом виде.
• Зависимости проверены на уязвимости (npm audit, pip-audit, govulncheck).

Производительность

Запуск без нагрузочного теста — лотерея. Бот может комфортно держать 50 RPS на dev и упасть на 200 RPS в момент рассылки.

• Load test пройден: минимум 100 RPS на webhook, P95 latency меньше 500 мс.
• Connection pool БД настроен под ожидаемую нагрузку (обычно 20–50 соединений на инстанс).
• Redis включён для FSM-состояний пользователей, персист (AOF или RDB) включён.
• Индексы БД созданы по chat_id, user_id, created_at и колонкам WHERE-фильтров.
• Медленные SQL-запросы профилированы (pg_stat_statements), P95 менее 200 мс.
• Кеш ответов LLM настроен (если используется): по нормализованному промпту с TTL от 1 до 24 часов.
• Память бота под нагрузкой не растёт линейно (нет утечек, проверка за час нагрузки).
• CDN настроен для статики и картинок.
• Webhook handler не делает синхронных запросов к внешним API дольше 500 мс.

Мониторинг

Без мониторинга вы узнаёте об инцидентах от пользователей в поддержке — это поздно и дорого.

• Sentry подключён с release tag, source maps загружены.
• Prometheus метрики экспортируются: RPS, latency P50/P95/P99, error rate, queue depth.
• Grafana дашборд: апдейты в минуту, успешные платежи, ошибки в минуту, latency.
• Алерты в отдельный Telegram-канал команды (не основной чат).
• Алерты на: 5xx больше 1%, latency P95 больше 1 секунды, queue depth больше 1000, webhook errors.
• Внешний uptime-check (UptimeRobot, Healthchecks.io, Яндекс.Мониторинг) пингует /health каждую минуту.
• Дашборд открыт у дежурного в первые 48 часов после запуска.

Логирование

• Структурированные JSON-логи (по одной строке на событие, ключи level, ts, msg, user_id).
• correlation_id пробрасывается от webhook через все внутренние вызовы.
• Log rotation настроен (logrotate, Docker max-size/max-file), не забивает диск.
• Retention соответствует 152-ФЗ: ПДн в логах хранятся не дольше необходимого срока.
• Sensitive data scrubbing: токены, телефоны, паспортные данные маскируются в логах (***).
• Логи отправляются в централизованное хранилище (Loki, ELK, Yandex Cloud Logging).

Бэкапы

Бэкап, который ни разу не восстанавливали, — не бэкап.

• PostgreSQL pg_dump ежедневно ночью, проверка успешности.
• Retention 14 дней (плюс еженедельные за месяц, плюс ежемесячные за год — по необходимости).
• Восстановление протестировано на стейджинге: dump разворачивается, бот стартует, данные на месте.
• Off-site копия в S3 / Yandex Object Storage в другой зоне доступности.
• Бэкап Redis (RDB-снапшот) для критичных FSM-состояний.
• Бэкап секретов (зашифрованный архив .env в безопасном месте).
• Документ «как восстановить продакшн с нуля» — пошагово, лежит в репозитории.

Юридическое (РФ)

Самый недооценённый блок. Штрафы за нарушение 152-ФЗ в новой редакции КоАП — до миллионов рублей за инцидент.

• Уведомление в РКН подано (если бот — оператор ПДн), регистрационный номер на руках.
• Уведомление о трансграничной передаче подано отдельно (Telegram — иностранная инфраструктура).
• Политика обработки ПДн опубликована и доступна по /privacy, ссылка в /start и в Mini App.
• Согласие на обработку ПДн запрашивается явной кнопкой перед сбором данных.
• Оферта (/offer) опубликована, если бот платный.
• 54-ФЗ: фискализация настроена, ОФД подключён, чеки выпускаются и доходят до клиента.
• В договоре с подрядчиком указано, кто оператор ПДн, кто исполнитель.
• Контактный email для запросов по ПДн (privacy@...) работает, ответ в пределах 30 дней.
• Возможность удаления данных пользователя (право на забвение) реализована и протестирована.

Маркетинг

• Ссылка t.me/your_bot работает, открывает бот в один клик с любого устройства.
• Deep links с UTM (t.me/your_bot?start=utm_src_email_camp_launch) проверены — параметры доходят до бэкенда.
• Ссылка добавлена в email-подписи команды, профили в соцсетях, футер сайта.
• README с описанием бота опубликован (Notion, корпоративный сайт).
• Инструкция первого использования (3–5 шагов с скриншотами) подготовлена.
• Превью-картинка для шаринга в мессенджерах настроена.

Поддержка

• Канал поддержки указан в /help и в футере Mini App.
• Runbook на типовые инциденты (webhook упал, БД недоступна, рассылка зависла) лежит в репозитории.
• On-call ротация согласована минимум на месяц вперёд.
• SLA первого ответа согласован (обычно 1–4 часа в рабочее время для B2C, 30 минут для B2B).
• У оператора есть «ручка» написать в чат пользователя из админки.
• FAQ-раздел внутри бота закрывает 60–80% типовых вопросов.

Аналитика

• Трекинг событий настроен: /start, ключевое действие, оплата, отписка.
• Дашборды в Metabase, Yandex DataLens или аналогах построены.
• Conversion funnel настроен: старт → ключевое действие → платёж.
• KPI baseline сняты на стейджинге или закрытом бета-тесте.
• Mini App подключён к Яндекс.Метрике или собственной аналитике.
• Сегменты по источнику трафика (UTM) выделены.
• Ретеншн (DAU, WAU, MAU) считается с первого дня.

Рассылки

Самый частый источник претензий и блокировок бота Telegram.

• Согласие на маркетинговые рассылки запрашивается отдельно от согласия на ПДн.
• Отписка одной кнопкой работает в каждом рассылочном сообщении.
• Rate limiter настроен: не более 30 сообщений в секунду глобально (лимит Telegram), не более 1 сообщения в секунду на чат.
• Тестовая рассылка по 100–500 пользователям прошла без ошибок.
• Логи рассылки сохраняют message_id и статус доставки.
• Шаблоны проверены на соответствие 38-ФЗ о рекламе (есть пометка «реклама», ИНН рекламодателя при необходимости).

Тесты

• Unit-покрытие критичных путей (платежи, авторизация, FSM-переходы) от 70%.
• Smoke-тесты после деплоя автоматически прогоняют ключевые сценарии.
• Ручное прохождение всех воронок: онбординг, основной сценарий, оплата, возврат, поддержка.
• Тестирование на разных устройствах: iOS, Android, десктоп Telegram, Telegram Web.
• Тестирование в разных условиях: светлая/тёмная тема, медленный интернет, оффлайн.
• Тестирование edge-кейсов: пользователь молчит 24 часа, бот добавлен в группу, повторный /start.
• Нагрузочный тест пройден (см. блок «Производительность»).

Стейджинг → прод

• Отдельные bot-токены для dev, staging и prod (никогда не один токен на все среды).
• Миграции БД отрепетированы на копии прод-данных.
• Rollback-план готов: откат на предыдущий Docker-образ за 5 минут.
• Blue-green или canary deployment настроен (опционально, но желательно).
• Бэкап БД сделан непосредственно перед переключением webhook.
• Возможность временно вернуть setWebhook на старую версию.
• Кнопка «выключить бот» (webhook на заглушку с сообщением о техработах) — на случай критичного инцидента.

Типовые ошибки, на которых горят запуски

Десяток антипаттернов, которые встречаются в каждом втором проекте.

• Один bot-токен на dev и прод. Разработчик тестирует фичу, токен случайно отвечает реальным пользователям с битым ответом.
• Webhook без secret_token. Любой, кто знает URL, может слать боту фейковые апдейты от имени Telegram.
• allowed_updates не задан. Бот получает chat_member, my_chat_member, chat_join_request и тратит ресурсы на ненужное.
• Long polling в проде. Работает в дев-среде, ломается под реальной нагрузкой и теряет апдейты при рестарте.
• Синхронный платёж в БД 1С. Эквайер вернул успех, 1С недоступна — клиент получил списание без заказа.
• Нет idempotency на webhook оплат. Платёжная система ретраит, бот дважды отправляет товар.
• Нет rate limit на рассылки. Telegram блокирует бот на 24 часа за превышение глобального лимита 30 сообщений в секунду.
• Логи с токенами и телефонами. При утечке логов в публичный канал — катастрофа.
• Бэкап без восстановления. Скрипт pg_dump отрабатывает каждую ночь, а файл уже месяц весит 0 байт из-за заполненного диска.
• Запуск в пятницу вечером. Команда уходит на выходные, инцидент тлеет до понедельника.

Soft-launch стратегия

Не выкатывать сразу на 100% аудитории — это базовое правило снижения риска. Идеальная схема:

1. 5% аудитории в первый день. Мониторинг 4–6 часов. Если метрики в норме (error rate меньше 1%, latency P95 в пределах SLA, нет всплесков в Sentry) — переход к следующему шагу.
2. 50% аудитории на 2–3 день. Мониторинг сутки. Дополнительная проверка: нагрузка на БД, очередь рассылок, recovery rate брошенных корзин.
3. 100% аудитории на 4–5 день. Дежурство сохраняется ещё минимум 72 часа.

Раскат удобно делать через флаг в БД (feature_flags.new_bot_enabled_for_user_id_mod_100 < 5) или через A/B-тулинг (Unleash, GrowthBook). На старом боте оставляйте сообщение-редирект для пользователей, ещё не попавших в раскат.

Post-launch неделя

• Дежурство в режиме on-call: 1–2 человека, чередование по 12 часов.
• Ежедневные стендапы команды по итогам предыдущих суток.
• Реакция на критичные алерты в пределах 30 минут.
• Разбор инцидентов (post-mortem) на каждый сбой длительностью более 15 минут.
• Отдельный канал обратной связи от пользователей (форма в боте, опрос через 24 часа).
• Ежедневный отчёт по KPI: новые пользователи, активация, retention day-1, конверсия в оплату.
• Ретроспектива через неделю: что прошло хорошо, что — нет, что улучшить к следующему запуску.

Документация и передача знаний

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

• README в репозитории описывает архитектуру: какие сервисы, какие очереди, какие БД.
• Диаграмма потоков данных (sequence diagram) для основных сценариев.
• Таблица переменных окружения с описанием каждой и примером значения.
• Инструкция «как запустить локально» работает у нового разработчика за 30 минут.
• Список внешних зависимостей: API курьеров, платёжных систем, CRM, LLM-провайдеров — с контактами поддержки.
• Журнал известных «грабель» (KNOWN_ISSUES.md): то, на что разработчики уже наступали.
• Контакты владельца продукта, технического лида, on-call дежурных — в одном документе.

Финальная проверка перед переключением

За 30 минут до запуска прогоняется быстрый smoke-тест на staging-боте с прод-конфигурацией:

Если хоть один пункт красный — запуск откладывается. Это правило кажется жёстким, но именно оно отделяет команды, у которых запуски проходят рутинно, от тех, у кого «всегда что-то горит».

День запуска

• Запуск утром буднего дня (вторник или среда — оптимально), не в пятницу и не перед длинными выходными.
• Команда на связи в одном чате с открытым дашбордом.
• График: за 30 минут до запуска проверка инфраструктуры, в момент запуска — переключение webhook, через 1 час — первая ретроспектива.
• Никаких миграций БД и обновлений зависимостей в день запуска.
• Готовый текст сообщения «извините, технические работы» на случай отката.
• Заблокированы все некритичные изменения в репозитории на 48 часов.

Итого

Запуск Telegram-бота — это не «нажал кнопку и пошло». Это последовательное прохождение чек-листа из 14 категорий, от продуктовых настроек в BotFather до post-launch дежурства. Блокеры (P0) — продукт, BotFather, технические настройки, безопасность, юридическое, бэкапы — должны быть закрыты на 100%. Желательное (P1) — производительность, мониторинг, логирование, тесты — закрывайте максимально, оставшееся допиливайте на soft-launch. Бонусные блоки (P2) — маркетинг, поддержка, аналитика, рассылки — добиваются в первую неделю после запуска. Soft-launch на 5% → 50% → 100% сокращает урон от любого недосмотра в разы. Хорошо подготовленный запуск проходит так, что команде нечего делать в первые сутки — это и есть нужный результат.

Частые вопросы

Что обязательно проверить в BotFather перед запуском?+

Финальные имя и юзернейм без _test и _dev, аватар не меньше 640×640, описание до 512 символов, about-текст до 120 символов, команды через setMyCommands с локализациями для всех целевых языков. Privacy mode включён, если бот в группах и не нужен полный доступ к сообщениям. Inline mode включён, если используется. Payment provider привязан (ЮKassa, CloudPayments, Stripe). Mini App URL прописан и кнопка меню ведёт на корректный адрес. Bot owner и backup admin — два разных Telegram-аккаунта, чтобы не потерять доступ.

Как правильно настроить webhook перед запуском Telegram-бота?+

HTTPS-сертификат действующий, желательно от Let's Encrypt с автообновлением. Webhook поставлен через setWebhook, ответ 200 на тестовый запрос. secret_token передан и проверяется на каждом входящем запросе через заголовок X-Telegram-Bot-Api-Secret-Token. allowed_updates указан явно — только нужные типы (message, callback_query, pre_checkout_query). getWebhookInfo показывает pending_update_count равный нулю и last_error_date равный null. Healthcheck-эндпоинт /health возвращает 200 быстрее 100 мс. Graceful shutdown: при SIGTERM воркер дорабатывает текущие апдейты до 30 секунд. Webhook отвечает быстрее 1–2 секунд, иначе Telegram повторяет апдейты.

Какие меры безопасности нужны перед запуском бота?+

Все секреты в env-vars или secrets manager (Vault, AWS Secrets Manager, Yandex Lockbox), не в git. Bot token ротирован минимум один раз, план ротации задокументирован. IP-allowlist Telegram на webhook (актуальные подсети проверить на core.telegram.org). Rate limit на уровне приложения (30 запросов в минуту на user_id). CAPTCHA на /start, если есть скам-риск. secret_token проверяется в каждом входящем запросе. Mini App проверяет initData через HMAC. Логи без токенов, паролей и телефонов в открытом виде. Зависимости проверены на уязвимости (npm audit, pip-audit, govulncheck).

Какие юридические документы нужны перед запуском бота в России?+

Уведомление в РКН подано, если бот — оператор ПДн. Отдельное уведомление о трансграничной передаче (Telegram — иностранная инфраструктура). Политика обработки ПДн опубликована и доступна по /privacy, ссылка в /start и Mini App. Согласие на обработку ПДн запрашивается явной кнопкой перед сбором данных. Оферта по /offer опубликована, если бот платный. По 54-ФЗ настроена фискализация, подключён ОФД, чеки выпускаются. Контактный email для запросов по ПДн работает с ответом в пределах 30 дней. Возможность удаления данных пользователя (право на забвение) реализована и протестирована. Без этих пунктов запуск возможен только с риском штрафов до миллионов рублей по новой редакции КоАП.

Как организовать soft-launch Telegram-бота?+

Раскат в три волны. Первый день — 5% аудитории, мониторинг 4–6 часов; если error rate меньше 1%, latency P95 в пределах SLA, нет всплесков в Sentry — переход к следующему шагу. Второй–третий день — 50% аудитории, мониторинг сутки, дополнительная проверка нагрузки на БД и очередь рассылок. Четвёртый–пятый день — 100% аудитории, дежурство сохраняется ещё минимум 72 часа. Раскат удобно делать через флаг в БД или через A/B-тулинг (Unleash, GrowthBook). На старом боте оставляйте сообщение-редирект для пользователей, ещё не попавших в раскат. Эта схема сокращает урон от недосмотров в разы.

Какой план отката нужен на случай проблем при запуске?+

Минимум четыре механизма. Откат на предыдущий Docker-образ за 5 минут — тег предыдущей версии всегда под рукой. Бэкап БД непосредственно перед переключением webhook. Возможность временно вернуть setWebhook на старый адрес, если развернули новую версию. Кнопка «выключить бот» — webhook на заглушку с сообщением о техработах, без полного даунтайма. План отката пишется до запуска, тестируется на стейджинге. Без него любой инцидент превращается в часовой простой и срочные митинги. Бэкап восстановления должен быть протестирован на стейджинге заранее: dump разворачивается, бот стартует, данные на месте.

Как организовать post-launch неделю после запуска бота?+

Дежурство в режиме on-call: 1–2 человека, чередование по 12 часов. Ежедневные стендапы по итогам предыдущих суток. Реакция на критичные алерты в пределах 30 минут. Разбор инцидентов (post-mortem) на каждый сбой длительностью более 15 минут. Отдельный канал обратной связи от пользователей — форма в боте или опрос через 24 часа. Ежедневный отчёт по KPI: новые пользователи, активация, retention day-1, конверсия в оплату. Ретроспектива через неделю: что прошло хорошо, что нет, что улучшить к следующему запуску. Запуск утром буднего дня, не в пятницу и не перед длинными выходными. Никаких миграций БД и обновлений зависимостей в первые 48 часов.