Как создать Telegram Mini App

Как создать мини приложение в ТГ, если нужен сервис для клиентов, а заставлять их скачивать еще одну программу из стора не хочется? Понадобятся три части: бот, зарегистрированный через BotFather, веб-интерфейс на HTML, CSS, JavaScript, который открывается по HTTPS, и сервер, который проверяет данные пользователя и хранит заказы. Мини-приложение Телеграм открывается поверх чата с ботом и выглядит как часть мессенджера.

Регистрация бота занимает пару минут. Основная работа, как и в любом веб-проекте, уходит на сценарий, дизайн и серверную часть. Дальше шаги идут в том порядке, в котором мы проходим их на проектах, с пометками, что делает заказчик, что делает разработчик и где обычно теряется время.

Что такое Telegram Mini App

Telegram Mini App - веб-приложение, которое открывается внутри Telegram поверх переписки с ботом. Технически это обычная веб-страница: ее верстают на HTML и CSS, логику пишут на JavaScript, размещают на своем сервере и отдают по HTTPS. От сайта ее отличает то, что страница получает от клиента Telegram данные о пользователе, цвета текущей темы, системные кнопки и доступ к платежам. Человек не вводит логин и пароль, ничего не ставит из стора и не уходит из чата.

Платформа вышла в 2022 году под названием Web Apps, позже Telegram переименовал ее в Mini Apps. Поэтому в документации, на форумах и в старых статьях встречаются оба варианта: Telegram Web App и Telegram Mini App означают одно и то же. Мини-приложение Telegram работает в мобильных клиентах для iOS и Android, в десктопных версиях и в Telegram Web.

Чем мини-приложение отличается от бота и от сайта

Бот общается командами и кнопками в чате. Для простых сценариев этого хватает: записаться на время, узнать статус заказа, задать вопрос. Как только нужно показать каталог на сотню товаров, фильтры, корзину, карту или календарь со слотами, переписка становится неудобной. Мини-приложение снимает это ограничение: бот остается точкой входа и каналом уведомлений, а сложный интерфейс открывается отдельным экраном.

От сайта мини-приложение отличается контекстом. Сайт нужно найти, открыть в браузере, пройти регистрацию. Мини-приложение открывается из чата, куда человек уже пришел, и сразу знает, кто он. Для бизнеса это короткий путь от рекламного поста в канале до оплаты.

Что такое Telegram Mini Apps для бизнеса

Если смотреть глазами владельца продукта, Telegram Mini Apps - это канал продаж и сервиса внутри мессенджера, которым аудитория пользуется каждый день. Приложение живет рядом с каналом компании, чатом поддержки и рассылками бота. Задача мини-приложения - дать пользователю закончить действие там, где он его начал: увидел пост, открыл каталог, оплатил.

Мини-приложения в ТГ обычно закрывают такие задачи:

• интернет-магазин с каталогом, корзиной и оплатой без перехода на сайт;
• запись на услуги для салонов, клиник, автосервисов, репетиторов;
• личный кабинет клиента с историей заказов, бонусами и статусами;
• программа лояльности и реферальные механики;
• внутренние инструменты для сотрудников: заявки, отчеты, согласования;
• игры и промо-механики для подписчиков канала.

Полноценное мобильное приложение мини-приложение не заменит там, где нужна глубокая работа с устройством, офлайн-режим или фоновые процессы. Зато оно быстрее доходит до человека: ссылку ставят в пост, в описание канала, в рассылку, и интерфейс открывается одним нажатием.

Примеры Telegram Mini Apps

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

• Грядка, доставка фермерских продуктов: каталог с фильтрами, корзина, выбор времени доставки, оплата, а статусы заказа присылает бот.
• Капиталика, финансовый сервис: личный кабинет с балансом и историей операций, вход по данным Telegram, а чувствительные действия подтверждаются отдельно.
• Трассер, логистика: курьер отмечает этапы доставки в приложении, клиент видит статус посылки прямо в чате, диспетчер получает сводку.

Как создать мини-приложение в Telegram: шаги по порядку

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

1. Сценарий и границы. Описываем, что пользователь делает в приложении, какие экраны нужны в первой версии, что уходит на потом. Здесь же решаем, нужна ли оплата, интеграция с CRM или 1С, роли сотрудников.
2. Бот. Заказчик создает бота через BotFather командой /newbot и получает токен. Регистрируйте бота на аккаунт компании, а не на личный номер разработчика, иначе при смене подрядчика можно потерять доступ.
3. Дизайн. Рисуем экраны с учетом того, что приложение открывается в окне мессенджера: узкая ширина, системная кнопка внизу, светлая и темная темы.
4. Фронтенд. Верстаем интерфейс и подключаем скрипт Telegram, который дает доступ к объекту window.Telegram.WebApp.
5. Бэкенд. Поднимаем сервер с API, базой данных, проверкой подписи пользователя и интеграциями.
6. Привязка к боту. В BotFather указываем адрес приложения: для кнопки меню в чате командой /setmenubutton или создаем мини-приложение со своей ссылкой командой /newapp.
7. Тестирование на реальных устройствах: iOS, Android, десктоп, веб-версия. Клиенты ведут себя по-разному в мелочах, и эти мелочи видит пользователь.
8. Запуск и продвижение: ссылка в канале, в описании бота, в рекламе.

Первые два шага заказчик может пройти сам еще до выбора подрядчика: описать сценарий своими словами и завести бота. Это экономит неделю переписки на старте.

Как создать Web App Telegram?

С точки зрения разработчика Telegram Web App - страница, которая подключает официальный скрипт и общается с клиентом мессенджера через JavaScript-объект. Первая строка, с которой начинается интеграция:

<script src='https://telegram.org/js/telegram-web-app.js'></script>

После загрузки скрипта на странице доступен объект window.Telegram.WebApp. Через него приложение:

• сообщает клиенту, что интерфейс готов, методом ready() и разворачивает окно на всю высоту методом expand();
• получает данные запуска в поле initData: кто открыл приложение, откуда, подпись для проверки;
• читает цвета темы из themeParams и подстраивает интерфейс под светлую или темную схему;
• управляет главной кнопкой внизу экрана (MainButton) и кнопкой Назад (BackButton);
• вызывает тактильную отдачу, всплывающие окна и окно оплаты.

Фреймворк выбирается свободно. Мы чаще собираем интерфейс на React с TypeScript, но Vue или связка HTML, CSS и чистого JavaScript тоже подходят. Для React есть открытые обертки над API Telegram, которые берут на себя подписку на события и работу с темой. Полное описание методов лежит в официальной документации для разработчиков на сайте Telegram, и сверяться с ней стоит перед каждым проектом: Bot API обновляется несколько раз в год.

Авторизация: как получить данные пользователя

Регистрация в мини-приложении обычно не нужна: клиент Telegram передает данные пользователя при каждом запуске. Доверять им на стороне браузера нельзя. Поле initDataUnsafe годится, чтобы показать имя в интерфейсе, а для входа используют строку initData целиком. Фронтенд отправляет ее на сервер, сервер вычисляет ключ из токена бота и сверяет хеш. Совпал - пользователь тот, за кого себя выдает, и можно выдавать сессию.

Этот шаг пропускают чаще всего, особенно в быстрых прототипах. Без проверки любой, кто знает адрес вашего API, подставит чужой идентификатор и увидит чужие заказы.

Как передать данные боту

Путей два. Первый - метод sendData: он отправляет строку боту и закрывает приложение. Объект перед отправкой сериализуют через JSON.stringify, например Telegram.WebApp.sendData(JSON.stringify(order)). Метод работает, только если приложение открыто с кнопки обычной клавиатуры бота, и объем данных у него ограничен.

Второй путь гибче: приложение отправляет данные на свой сервер, а сервер через Bot API пишет пользователю сообщение, присылает чек или уведомление о статусе. На проектах мы почти всегда выбираем его, потому что так заказы попадают в базу и CRM, даже если человек закрыл окно.

Оплата внутри Telegram

Приложение может открыть окно оплаты, не выводя человека из мессенджера. Сервер создает счет через Bot API, фронтенд открывает его методом openInvoice. Для физических товаров и услуг подключают платежного провайдера через BotFather. Цифровые товары и подписки внутри Telegram по правилам платформы продают за Telegram Stars (внутреннюю валюту мессенджера).

Есть и третий вариант: собственный эквайринг, когда пользователь переходит на платежную страницу банка и после оплаты возвращается в приложение. Какой путь выбрать, зависит от типа товара и требований бухгалтерии. Это решаем на этапе сценария, а не за неделю до запуска.

Стек и архитектура мини-приложения

Типовая архитектура у нас состоит из четырех частей:

• фронтенд: React и TypeScript, сборка через Vite, статика на CDN или на своем сервере с HTTPS;
• бэкенд: Node.js или Python, REST API, проверка initData, логика заказов и ролей;
• база данных: чаще PostgreSQL, для кеша и очередей Redis;
• бот: принимает команды, отправляет уведомления, выдает ссылку на приложение; живет рядом с API или отдельным сервисом.

Отдельно продумываем интеграции. Если товары и остатки лежат в 1С, а клиенты в CRM, мини-приложение берет данные оттуда, а не из таблицы, которую менеджер правит руками. Для небольшого проекта хватает простой админки, где сотрудник меняет каталог и видит новые заказы.

Что учесть в интерфейсе

Окно мини-приложения на телефоне узкое, а сверху у него шапка Telegram, которую приложение не контролирует. Поэтому:

• главное действие выносим в MainButton, пользователи мессенджера к ней привыкли;
• поддерживаем обе темы и берем цвета из themeParams, иначе светлое приложение будет слепить в темном клиенте;
• обрабатываем системную кнопку Назад вместо своей стрелки;
• учитываем, что свайп вниз в некоторых сценариях сворачивает окно, и не прячем туда важные жесты;
• держим вес первой загрузки маленьким: приложение часто открывают в дороге с мобильным интернетом.

В свежих версиях Bot API у мини-приложений добавились полноэкранный режим и ярлык на главном экране телефона. Если такие функции важны для сценария, проверяем их поддержку в актуальной документации до начала дизайна.

Публикация и продвижение

Проходить ревью, как в App Store, перед запуском не нужно: приложение доступно, как только вы привязали его к боту. Открыть его можно несколькими способами:

• кнопка меню в чате с ботом;
• инлайн-кнопка под сообщением бота или под постом в канале;
• прямая ссылка вида t.me/имя_бота/имя_приложения, которую можно поставить куда угодно;
• кнопка обычной клавиатуры бота.

Основной трафик приходит из собственных площадок компании: пост с кнопкой, закреп, ссылка в описании канала, рассылка по базе бота. Для холодной аудитории работают реклама в каналах и посевы с прямой ссылкой. В ссылку можно добавить стартовый параметр, приложение получит его при запуске, и по нему видно, какой источник принес пользователя.

После запуска бот становится каналом удержания: напоминает о брошенной корзине, сообщает статус заказа, присылает персональные предложения. Здесь легко перегнуть. Навязчивого бота блокируют одной кнопкой, и вернуть такого пользователя почти невозможно.

От чего зависит бюджет

Стоимость мини-приложения складывается так же, как у любого веб-продукта: аналитика, дизайн, фронтенд, бэкенд, тестирование, управление проектом. Сильнее всего на смету влияют:

• число экранов и ролей: покупатель, курьер, менеджер, администратор;
• оплата и ее схема;
• интеграции с 1С, CRM, складом, службами доставки;
• админка для управления контентом;
• нагрузка: игра с тысячами одновременных игроков требует другой архитектуры, чем запись в салон.

Точную цифру называем после брифа. Для первой прикидки подойдет калькулятор стоимости: он спросит про функции и выдаст ориентир. Как мы ведем такие проекты от сценария до поддержки, описано на странице разработки Telegram Mini App.

Частые ошибки при создании мини-приложения

• Бот зарегистрирован на личный аккаунт фрилансера. Когда сотрудничество заканчивается, компания теряет токен и настройки.
• Нет проверки initData на сервере. Это дыра в безопасности, а не мелкая недоработка.
• Интерфейс перенесли с сайта без адаптации. Шапка сайта, свое меню и футер внутри мессенджера мешают и выглядят чужими.
• Забыли про темную тему. Многие держат клиент в темном оформлении, и белый экран в нем режет глаза.
• Не проверили на старых телефонах и десктопе. Встроенный браузер на Android ведет себя иначе, чем на iOS, а десктопный клиент открывает приложение в отдельном окне с другими размерами.
• Нет аналитики. Без меток в ссылках не понять, какой пост или какая реклама принесли заказы.

Похожие механики есть во ВКонтакте и в MAX. Если аудитория разделена между мессенджерами, клиентскую часть можно переиспользовать, а связь с платформой вынести в отдельный слой.