Материал для тех, кому предстоит довести Mini App от идеи до боевого запуска и кто хочет заранее понимать последовательность работ. Разбор идёт по этапам: регистрация, инфраструктура, подключение SDK, авторизация, данные, платежи, уведомления, тестирование, публикация. В конце — список мест, где проекты чаще всего спотыкаются.

Шаг 1. Бот и регистрация приложения

Точка входа всегда одна — бот. Он создаётся в BotFather, там же выдаётся токен, который дальше служит и ключом к Bot API, и основой для проверки подписи. После создания бота регистрируется само приложение: указывается заголовок, описание, изображение и URL, по которому лежит веб-часть. На выходе получается короткая ссылка вида t.me/имя_бота/app — по ней Mini App открывается напрямую, минуя диалог. Параллельно настраивается кнопка меню в чате: она ведёт на тот же адрес и служит постоянным входом для тех, кто уже подписан.

Шаг 2. Хостинг, домен, HTTPS

Веб-часть — это обычное SPA или серверно отрендеренное приложение. Требования жёсткие: валидный сертификат, стабильный ответ, отсутствие редиректов на промежуточные домены. Стоит сразу развести два контура — тестовый и боевой, каждый со своим ботом и своим токеном. Смешивать их нельзя: подпись initData считается от конкретного токена, и тестовые запросы в боевом контуре просто не пройдут проверку.

Шаг 3. Подключение Telegram Web Apps SDK

В разметку подключается официальный скрипт, после чего в глобальном объекте появляется API веб-приложения. Минимальный набор вызовов при старте: сообщить о готовности интерфейса, развернуть окно на доступную высоту, включить подтверждение закрытия, если внутри есть незавершённая форма. Оттуда же приходят параметры темы — цвета фона, текста, кнопок и подсказок. Их надо прокидывать в CSS-переменные, иначе приложение будет выглядеть инородно у половины пользователей, сидящих в тёмной теме.

Отдельно настраиваются системные элементы: главная кнопка внизу экрана, кнопка «назад» в заголовке, тактильная отдача при действиях. Собственные кнопки, нарисованные поверх, ломают ощущение среды — среда даёт свои, и правильнее пользоваться ими. Что входит в такую работу на нашей стороне, описано на странице Telegram Mini App.

Шаг 4. Авторизация через initData

Это самое ответственное место всего проекта. При открытии приложение получает строку initData: идентификатор пользователя, имя, язык, метку времени, параметр запуска и подпись. Клиентская часть передаёт эту строку на сервер в заголовке запроса, и дальше всё решается там.

  1. Разобрать строку в пары «ключ-значение», убрать из набора поле hash.
  2. Отсортировать оставшиеся пары по имени ключа и склеить в строку проверки через перевод строки.
  3. Получить секретный ключ: HMAC-SHA256 от токена бота с ключом-константой WebAppData.
  4. Посчитать HMAC-SHA256 от строки проверки этим секретным ключом и сравнить с присланным hash.
  5. Проверить auth_date: слишком старые данные отклонять, иначе перехваченную строку можно переиспользовать.

Только после успешной проверки сервер создаёт свою сессию. Доверять идентификатору пользователя, пришедшему с клиента без сверки подписи, нельзя ни при каких условиях — подменить его тривиально.

Шаг 5. Данные и API

Дальше архитектура обычная: REST или GraphQL, серверная валидация, пагинация списков, кэш на клиенте. Специфика Telegram в том, что окно живёт недолго и часто открывается заново, поэтому холодный старт критичен. Тяжёлые сборки, огромные шрифты и неоптимизированные картинки бьют по конверсии сильнее, чем на сайте: пользователь пришёл из чата и уйдёт обратно в чат при первой заминке. Каталог на несколько тысяч позиций требует серверного поиска и подгрузки по мере прокрутки — тянуть весь массив на клиент бессмысленно. Практику построения витрины мы собрали в разделе про магазин на Telegram Mini App.

Шаг 6. Платежи

Для физических товаров и услуг подключается обычный эквайринг и Kaspi — то есть внешний платёжный провайдер со своим договором, тестовым контуром и вебхуками. Для цифровых товаров внутри Telegram предусмотрены Stars, и это отдельный сценарий. Инженерная часть здесь не в кнопке оплаты, а в идемпотентности: вебхук может прийти дважды, порядок событий не гарантирован, а пользователь способен закрыть окно ровно между списанием и подтверждением. Заказ должен переходить в оплаченный статус по подтверждению от провайдера, а не по возврату пользователя на экран «спасибо».

Шаг 7. Уведомления

Само приложение отправлять сообщения не умеет. Всё, что видит клиент после закрытия окна, шлёт бот обычным сообщением в чат по Bot API. Отсюда практическое следствие: у сервера должна быть связка «идентификатор пользователя Telegram — заказ», иначе после оплаты писать будет некому. Сценарии оформляются заранее, вместе с текстами и правилами частоты. Если диалоговая часть разрастается, её выносят в самостоятельный контур — этим занимается направление чат-ботов.

Шаг 8. Аналитика и параметр запуска

Источник перехода определяется параметром запуска: в ссылку на приложение подставляется метка, она приходит вместе с initData и позволяет отделить трафик из канала от трафика из рассылки или наружной рекламы. Стандартные UTM тут не работают привычным образом, поэтому схему меток проектируют заранее и фиксируют на сервере вместе с сессией. Продуктовые события — открытие карточки, добавление в корзину, старт оплаты — отправляются с бэкенда, а не с клиента: так они не теряются при закрытии окна на середине сценария.

Шаг 9. Тестирование

  • Проверять на реальных устройствах, обязательно на iOS и на Android — поведение клавиатуры, безопасных зон и высоты окна отличается.
  • Прогнать светлую и тёмную тему.
  • Смоделировать медленную сеть и обрыв связи на середине оформления.
  • Проверить повторное открытие приложения с уже начатой корзиной.
  • Отдельно протестировать оплату: успех, отказ, таймаут, двойной вебхук, возврат.
  • Убедиться, что запрос с испорченной подписью initData отклоняется сервером.

Где проекты спотыкаются

  • Проверка подписи сделана на клиенте или не сделана вовсе.
  • Тестовый и боевой боты используют один токен, и подпись перестаёт сходиться после переключения.
  • Интерфейс прибит к светлой теме и становится нечитаемым у половины аудитории.
  • Пользователю показывают собственную кнопку «назад» вместо системной, и навигация начинает конфликтовать с жестами.
  • От Mini App ждут работы без сети, доступа к системным возможностям телефона или тяжёлой графики — это территория нативной разработки, и такие требования честнее закрывать через мобильное приложение.
  • Не продуман возврат в чат: после оплаты человек остаётся в подвешенном окне и не получает подтверждения.

Порядок шагов важнее скорости. Проекты, где авторизацию и платёжные сценарии проектируют в начале, а не после первого запуска, обходятся дешевле и переживают рост нагрузки без переписывания.