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

Telegram Mini App — это веб-приложение, которое открывается внутри мессенджера. Человек нажимает кнопку в чате и попадает в каталог, личный кабинет или другую рабочую область. Устанавливать отдельную программу на смартфон не требуется.

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

Разберём весь процесс: от выбора идеи и создания бота до программирования, размещения на VPS и публикации готового продукта.

Что такое Telegram Mini App и как он работает

Mini App, или Web App, — обычный веб-сервис, который открывается во встроенном браузере мессенджера. Внешне он напоминает мобильный сайт: посетитель видит страницы, карточки, формы и элементы навигации. Дополнительно разработчик получает инструменты интеграции с платформой.

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

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

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

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

Обычно оба инструмента работают вместе. Бот служит точкой входа и каналом уведомлений, а веб-часть отвечает за каталог, оформление заказов и личный кабинет.

Из каких частей состоит проект

Для начала достаточно разобраться в четырёх компонентах:

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

Эти компоненты взаимодействуют через API — набор правил, по которым веб-страница обращается к серверной системе. Например, один запрос получает каталог услуг, а другой создаёт новое бронирование.

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

Как выбрать идею и спланировать разработку

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

Определите аудиторию

Представьте конкретную ситуацию. Человек впервые открывает Ваш сервис. Что он хочет найти и сколько времени готов потратить?

Допустим, вы создаёте площадку для поиска исполнителей. Заказчику необходимо разместить поручение и выбрать специалиста, а исполнителю — просмотреть предложения и отправить отклик. Их цели различаются, поэтому разделы и доступные возможности тоже могут отличаться.

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

Выберите функции первой версии

MVP — минимально жизнеспособный продукт. Он содержит только основные возможности, но уже позволяет решить конкретную задачу. Например, для бронирования услуг достаточно каталога, календаря, оформления заявки и просмотра своих посещений. Программу лояльности, подарочные сертификаты и персональные рекомендации можно добавить позднее.

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

Продумайте пользовательский путь

Запишите, как человек пройдёт от первого открытия до результата. Например:

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

Какие технологии нужны для Mini App

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

Frontend: видимая часть

HTML задаёт содержимое страницы, CSS отвечает за оформление, а JavaScript обрабатывает нажатия и ввод. Например, HTML создаёт форму заказа, а JavaScript передаёт её содержимое на сервер.

Для простого прототипа этого достаточно. Если планируется много экранов и сложная навигация, можно выбрать React с TypeScript и использовать Vite для сборки проекта.

Но конкретный фреймворк не является обязательным. Если команда уже работает с Vue или другим подходящим инструментом, менять технологию ради веб-формата необязательно.

Backend: обработка запросов

Серверная часть выполняет операции, которым нельзя доверять браузеру. Например, подтверждает личность, контролирует права, сохраняет заказы и обрабатывает платежи.

Представьте, что посетитель отправляет заявку. Frontend передаёт заполненную форму, backend проверяет её содержимое и сохраняет результат в базе.

Для реализации подойдут Node.js, Python, PHP, Go и другие языки. В небольшом проекте на JavaScript часто используют Express, а для более сложной архитектуры можно рассмотреть NestJS.

Хранение информации

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

Необязательно сразу добавлять Redis, очереди сообщений и другую инфраструктуру. Такие инструменты подключают, когда появляется конкретная техническая потребность.

Если компания уже имеет сайт с готовым API, встроенную веб-часть разумно связать с ним. Тогда заказ, оформленный через мессенджер, сразу появится в общей системе без ручного переноса.

Как создать Telegram-бота и подключить Mini App

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

1. Откройте BotFather. Найдите официальный аккаунт и начните диалог.
2. Отправьте /newbot. Эта команда запускает создание нового бота.
3. Укажите название. Например, Demo Task App.
4. Выберите username. Имя должно быть свободным и соответствовать правилам платформы.
5. Сохраните Bot Token. Секрет понадобится для обращения к Bot API.
6. Оформите профиль. Добавьте аватар, описание и при необходимости команды.

Токен даёт программе полномочия управлять ботом. Поэтому не размещайте его в HTML, публичном репозитории и JavaScript, который загружает браузер. Для хранения используйте переменные окружения или менеджер секретов.

Как настроить открытие веб-сервиса

Когда сайт будет опубликован по HTTPS, свяжите его с созданным ботом.

1. Откройте /mybots. Выберите нужный аккаунт.
2. Перейдите в настройки Mini App. Найдите параметры главного веб-приложения.
3. Укажите адрес. Например, https://mini.example.com. Вместо условного домена понадобится собственный.
4. Настройте точку входа. Для полноценного продукта удобен Main Mini App. Дополнительно можно включить Menu Button — постоянную кнопку в чате.
5. Протестируйте открытие. Запустите страницу со смартфона и убедитесь, что она загружается без ошибок.

Названия отдельных пунктов BotFather могут меняться. Постоянную кнопку также настраивают через команду /setmenubutton.

Для переходов из канала или рекламы подходит прямая ссылка, например:
https://t.me/your_bot_username?startapp

Имя your_bot_username замените на собственное. При наличии короткого имени главного приложения можно использовать соответствующий формат адреса.

Как разработать интерфейс

Для первого прототипа возьмём простой сценарий: просмотр личных заданий и добавление новых. Понадобятся Node.js, npm и редактор кода.

1. Создайте проект. Выполните команды:
   mkdir telegram-mini-demo
   cd telegram-mini-demo
   npm init -y
   npm install express dotenv

Подготовьте public/index.html для веб-страницы, server.mjs для обработки запросов и .env для конфигурации. Файл с секретами исключите из публичного Git-репозитория.

1. Подключите WebApp API. В HTML добавьте официальный скрипт:

После загрузки внутри клиента станет доступен объект window.Telegram.WebApp. Через него можно работать с параметрами запуска, оформлением и системными элементами.

1. Инициализируйте страницу. Метод ready() сообщает о готовности интерфейса, а expand() позволяет запросить большую высоту окна. Дополнительные возможности используйте с учётом поддержки в конкретной версии клиента.
2. Создайте рабочий экран. Добавьте список заданий, поле ввода и кнопку отправки. После заполнения формы JavaScript обращается к API, а серверная часть сохраняет новую запись.
3. Покажите результат. После успешного запроса обновите содержимое страницы. Если возникла ошибка, выведите понятное сообщение и предусмотрите повторную отправку без дублирования заявки.
4. Адаптируйте страницу для смартфона. Учитывайте экранную клавиатуру, размеры кнопок, прокрутку и расположение нижней навигации. Важные элементы не должны перекрываться системными областями.

Для оформления можно применять CSS-переменные WebApp API. Они помогают согласовать цвета страницы с темой мессенджера. Навигацию также желательно связать с системной кнопкой возврата, чтобы переход из карточки обратно в каталог работал предсказуемо.

Актуальные возможности описаны в документации Telegram Mini Apps.

Как настроить авторизацию пользователей

При открытии веб-сервиса Telegram передаёт строку initData. Она содержит сведения о запуске и криптографическую подпись, которая позволяет подтвердить их подлинность. Проверку необходимо выполнять на серверной стороне. Иначе злоумышленник сможет попытаться подменить идентификатор профиля и обратиться к чужой информации.

1. Получите initData. Frontend обращается к Telegram.WebApp.initData и передаёт исходную строку на backend через HTTPS.
2. Извлеките поля. Сервер разбирает параметры, включая hash, auth_date и сведения о профиле, если они присутствуют.
3. Подготовьте строку проверки. Все параметры, кроме hash, сортируют по ключам и соединяют в формате key=value, используя перевод строки как разделитель.
4. Вычислите подпись. Для проверки через токен бота применяется HMAC-SHA256 по алгоритму Telegram. Секретный ключ получают с использованием константы WebAppData.
5. Сравните значения. Если вычисленная подпись не совпала с переданным hash, авторизацию отклоняют. Сравнение следует выполнять способом, устойчивым к атакам по времени выполнения.
6. Оцените срок действия. Поле auth_date помогает определить возраст сведений о запуске. Слишком старые запросы не должны давать бессрочный доступ.
7. Определите права. После подтверждения подлинности backend находит профиль и устанавливает, какие разделы и операции ему доступны.

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

Как связать профиль с аккаунтом сайта

Если человек уже зарегистрирован на основном ресурсе, его учётную запись необходимо безопасно связать с Telegram ID.
Авторизуйтесь на сайте. Откройте настройки профиля.

1. Начните привязку. Система создаёт временный код или одноразовую ссылку.
2. Подтвердите действие через бота. Backend сверяет полученные сведения и срок действия подтверждения.
3. Сохраните соответствие аккаунтов. После успешной проверки человек сможет пользоваться существующими заказами и настройками.

Не объединяйте профили автоматически только по совпадению имени. Для изменения платёжных реквизитов и других чувствительных сведений желательно предусмотреть дополнительное подтверждение.

Как разместить Mini App на VPS

Для постоянной работы потребуется публичный HTTPS-адрес. Подойдёт виртуальный сервер с Linux, например Ubuntu Server 24.04 LTS.
В типовой конфигурации Node.js выполняет серверную логику, Nginx принимает внешние запросы, а Certbot помогает настроить сертификат Let’s Encrypt.

1. Подготовьте VPS. Установите необходимое ПО и создайте отдельного системного пользователя с ограниченными правами.
2. Перенесите проект. Скопируйте файлы, установите зависимости и заполните конфигурацию. Секреты не должны находиться в публичном каталоге.
3. Запустите backend локально. Например, он может слушать 127.0.0.1:3000. Внутренний порт лучше не открывать для внешних соединений.
4. Настройте Nginx. Направьте запросы с домена mini.example.com на локальный процесс. Предварительно создайте корректную DNS-запись.
5. Подключите HTTPS. Выпустите сертификат и настройте его продление. Убедитесь, что страница открывается по защищённому адресу.
6. Организуйте постоянную работу. Через systemd можно настроить запуск процесса после перезагрузки и автоматическое восстановление при сбое.
7. Зарегистрируйте webhook. В Bot API предусмотрен метод setWebhook. Например, адрес получения событий может выглядеть так: https://mini.example.com/telegram/webhook.
8. Убедитесь в правильности настройки. Используйте getWebhookInfo и отправьте тестовую команду боту.

Для webhook рекомендуется задать secret_token. Сервер сможет сверять его с HTTP-заголовком входящего запроса и отклонять обращения без нужного секрета.

Webhook получает события от бота, например команду /start. А создание заказа или изменение профиля из веб-страницы обычно происходит через обычный API.

Какие функции Telegram можно добавить

После запуска основного сценария продукт можно расширить такими дополнительными возможностями, как:

• Уведомления. Сообщения о новых заказах, изменении статуса или подтверждении бронирования. Учитывайте право бота на общение с человеком и предусмотрите настройки частоты оповещений.
• Навигация и оформление. WebApp API поддерживает взаимодействие с системными элементами, изменение высоты окна и тактильную обратную связь. Цвета страниц можно согласовать с оформлением мессенджера.
• Прямые ссылки и приглашения. Переходы из канала, рекламы или личной переписки помогают открыть нужный раздел. Стартовые параметры пригодятся для анализа источников трафика, но не должны самостоятельно предоставлять доступ к закрытой информации.
• Возможности устройства. В зависимости от версии клиента доступны механизмы работы с QR-кодами, геолокацией и отдельными функциями смартфона. Например, сканирование может пригодиться при проверке электронных билетов.

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

Как подключить оплату

Порядок расчётов зависит от того, что продаётся внутри мессенджера.

Цифровой контент и услуги. Для таких покупок Telegram предусматривает Stars с валютой XTR. Продажа цифрового содержимого внутри бота или веб-приложения должна соответствовать правилам этой платёжной системы.

Чтобы подключить оплату:

1. Создайте счёт. Используйте sendInvoice или createInvoiceLink с подходящими параметрами.
2. Откройте платёжную форму. Покупатель подтверждает приобретение через Telegram.
3. Обработайте pre_checkout_query. На предварительный запрос необходимо ответить через answerPreCheckoutQuery в установленный срок — не более десяти секунд.
4. Получите successful_payment. Это событие подтверждает успешную транзакцию.
5. Сохраните её идентификатор. Повторное получение одного события не должно приводить к повторной выдаче покупки.
6. Откройте оплаченный продукт. Доступ предоставляют после достоверного подтверждения.

Отдельно предусмотрите отмену платежа, ошибки обработки и возврат средств. Подробности описаны в документации Telegram Stars.

Физические товары. Для них используются другие платёжные механизмы с поддерживаемыми провайдерами. Перед подключением уточните условия расчётов и требования законодательства.

Если создаётся маркетплейс с выплатами исполнителям, финансовую модель потребуется продумать отдельно. Stars не являются универсальной заменой банковского эквайринга или готовой системой безопасной сделки.

Как протестировать Mini App перед публикацией

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

1. Оцените мобильное отображение. Откройте страницы на Android и iOS, заполните формы и проверьте поведение экранной клавиатуры. Текст и важные элементы не должны перекрываться.
2. Протестируйте другие устройства. В Desktop и веб-версии посмотрите, как меняются ширина карточек, навигация и прокрутка. Проверьте оба варианта оформления.
3. Пройдите путь от начала до результата. Например, найдите товар, добавьте его в корзину, оформите заказ и откройте историю покупок.
4. Создайте нестандартные ситуации. Отключите интернет, отправьте пустую форму или дважды нажмите кнопку отправки. Система должна сообщать об ошибке и не создавать дубли.
5. Испытайте защиту. Попробуйте открыть чужой заказ, изменить идентификатор объекта или передать неподтверждённые сведения авторизации. Такие запросы необходимо отклонять.
6. Протестируйте платежи и восстановление. Если предусмотрена касса, проверьте отмену, повторное событие и сбой после успешного списания. Отдельно убедитесь, что резервные копии позволяют восстановить хранилище.

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

Как опубликовать Mini App и привлечь аудиторию

Для обычного веб-продукта внутри Telegram не требуется отдельная публикация в App Store или Google Play. После размещения сайта и подключения к боту можно готовить публичный запуск.

1. Завершите техническую настройку. Убедитесь в доступности HTTPS, исправности авторизации и работе основных сценариев.
2. Оформите профиль. Добавьте понятное название, аватар и краткое описание пользы. При наличии соответствующих настроек используйте скриншоты и демонстрационные материалы.
3. Подготовьте ссылки. Разместите их в канале, сообщениях или рекламных публикациях. При необходимости добавьте параметры для определения источника перехода.
4. Настройте аналитику. Отслеживайте открытия, успешные входы, просмотры каталога и завершённые операции. Для этого подойдёт PostHog или другой инструмент.
5. Включите мониторинг. Следите за доступностью API, ошибками авторизации, проблемами оплаты и состоянием инфраструктуры.
6. Начните с ограниченной аудитории. Соберите обратную связь, устраните обнаруженные недостатки и только после этого расширяйте продвижение.

Для аналитики можно использовать события mini_app_opened, telegram_auth_succeeded, catalog_viewed, order_created и payment_succeeded.

Успех лучше оценивать не только по посещениям, но и по выполнению целевого сценария. Например, для бронирования важно понимать, сколько посетителей действительно завершили оформление и на каком этапе остальные прекратили работу.

Частые ошибки при разработке

• Перенос большого сайта без адаптации. Многоуровневое меню и длинные формы становятся неудобными на смартфоне. Лучше выделить востребованные функции и подготовить отдельную мобильную навигацию.
• Недостаточная защита аккаунтов. Подлинность сведений о входе и права на каждую закрытую операцию необходимо контролировать на серверной стороне.
• Публикация секретов. Bot Token и закрытые API-ключи не должны попадать в браузерный JavaScript или открытый репозиторий.
• Ненадёжное хранение. Для заказов и профилей требуется постоянная база с резервным копированием, а не временные переменные приложения.
• Неправильная обработка платежей. Открытие формы ещё не означает успешную покупку. Учитывайте подтверждение транзакции и защиту от повторной выдачи товара.
• Избыточный MVP. Сложная архитектура и множество необязательных модулей затягивают выход на рынок. Сначала доведите до стабильной работы один законченный сценарий.
• Отсутствие наблюдения за ошибками. Команда должна узнавать о сбоях API и проблемах с оплатой из мониторинга, а не только после жалоб.

Заключение

Telegram Mini App можно разработать на стандартных веб-технологиях. Для этого понадобятся бот, графический интерфейс, серверная логика и при необходимости база данных. Мессенджер обеспечивает точку входа и инструменты интеграции, а работа продукта остаётся на стороне разработчика.

Начните с конкретной задачи и небольшого MVP. Затем настройте бота, создайте веб-часть, подключите авторизацию и разместите проект по HTTPS. Перед публикацией проверьте основные сценарии на разных устройствах и устраните технические ошибки.

Если у компании уже есть сайт с готовым API, разумно использовать существующую инфраструктуру. Это сократит дублирование логики и упростит развитие. Главное — сделать основные функции понятными, безопасными и стабильными.