Как создать Telegram Mini App: пошаговая инструкция

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

Шаг 1. Создайте бота

Mini App всегда привязан к боту. В Telegram откройте @BotFather, отправьте команду /newbot, задайте имя и username (он заканчивается на bot). BotFather выдаст токен бота. Токен храните только на сервере и не публикуйте в коде страницы.

Шаг 2. Подготовьте страницу

Telegram открывает адрес, который вы укажете, поэтому страницу нужно где-то разместить. Главное требование: адрес должен работать по HTTPS. Подойдёт обычный хостинг, VPS или статический хостинг. Для первой версии хватит одного index.html.

Шаг 3. Подключите Telegram Web App

В <head> добавьте скрипт Telegram и обратитесь к объекту Telegram.WebApp:

<script src="https://telegram.org/js/telegram-web-app.js"></script>
<script>
  const tg = window.Telegram.WebApp;
  tg.ready();    // сообщаем Telegram, что страница загружена
  tg.expand();   // раскрываем окно на всю высоту
  document.getElementById('hello').textContent =
    'Привет, ' + (tg.initDataUnsafe.user?.first_name || 'гость');
</script>

Что полезно знать на старте:

• tg.themeParams отдаёт цвета темы Telegram, по ним можно подстроить оформление под светлую и тёмную тему.
• tg.MainButton — большая кнопка внизу окна для главного действия, например «Оформить заявку».
• tg.BackButton — кнопка «назад» в шапке окна.

Шаг 4. Свяжите Mini App с ботом

Открыть Mini App можно несколькими способами:

1. Кнопка меню бота. Задаётся в настройках бота через @BotFather: указываете адрес страницы, и кнопка появляется рядом с полем ввода.
2. Кнопка в сообщении. Бот отправляет inline-кнопку или кнопку клавиатуры с типом web_app и адресом страницы.
3. Прямая ссылка. Команда /newapp у @BotFather регистрирует Mini App и даёт ссылку вида t.me/ваш_бот/название. Её можно разместить на сайте, в канале или превратить в QR-код.

Шаг 5. Проверьте пользователя на сервере

Данные в initDataUnsafe приходят с клиента, поэтому им нельзя доверять: пользователь может подделать запрос. Если Mini App что-то записывает или показывает личные данные, отправляйте на сервер строку tg.initData и проверяйте подпись токеном бота. Как это сделать на Python, описано в статье проверка initData в Telegram Mini App.

Шаг 6. Проверьте на реальных устройствах

Откройте Mini App в Telegram на телефоне и на компьютере. Проверьте:

• светлую и тёмную тему;
• маленький экран и клавиатуру, которая закрывает поля ввода;
• что страница не ломается при медленном соединении;
• как работает кнопка «назад».

Что добавить дальше

После первой версии обычно нужны уведомления пользователям (как их настроить), каталог с фильтрами (архитектура каталога) и связка с сайтом, который остаётся для поиска. Если вы выбираете между сайтом и Mini App, сравнение есть в статье Mini App или сайт. Ориентиры по цене собраны в материале сколько стоит бот и Mini App.

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