Разработка Telegram Mini App

Чем Telegram Mini App отличается от обычного бота

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

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

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

Выберите услугу
↓
Выберите дату
↓
Выберите время
↓
Подтвердите запись

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

После нажатия кнопки или открытия приложения пользователь видит обычный графический интерфейс прямо внутри Telegram:

Telegram
↓
Mini App
↓
Каталог / форма / календарь / кабинет

Но это не значит, что Mini App — «улучшенная версия бота». У них разные задачи.

Бот и Mini App могут работать вместе

Одна из самых полезных схем выглядит так:

Telegram-бот
     ↓
открывает Mini App
     ↓
пользователь работает с интерфейсом
     ↓
backend / база данных / внешний API
     ↓
бот отправляет результат или уведомление

Например, пользователь открывает через бота Mini App интернет-магазина, выбирает товары, оформляет заказ, а затем получает от бота сообщение:

Заказ №125 принят.
Мы сообщим, когда он будет готов.

Или записывается через календарь Mini App, после чего бот напоминает о записи.

Поэтому при проектировании Telegram-сервиса полезнее спрашивать не «бот или Mini App?», а «какую часть задачи удобнее оставить в чате, а для какой нужен интерфейс?»

Что можно сделать в Telegram Mini App

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

• каталог товаров или услуг;
• карточки товаров;
• корзина;
• оформление заказа;
• запись на услуги;
• календарь и выбор времени;
• личный кабинет;
• история заказов;
• статусы заявок;
• программа лояльности;
• бонусный баланс;
• калькулятор стоимости;
• многошаговая форма;
• анкета или квиз;
• таблицы и списки;
• внутренние панели управления;
• работа с существующим API;
• интеграция с CRM;
• подписки;
• работа с внешними сервисами;
• оплата;
• сервис для сотрудников или клиентов.

Фактически ограничение определяется уже не форматом Telegram-сообщения, а архитектурой самого приложения. Но Mini App нужен далеко не для каждой задачи.

Каталог
├─ Поиск
├─ Категории
├─ Фильтры
├─ Корзина
└─ Оформление заказа

Услуга → специалист
→ дата → время → подтверждение

Сотрудник → заявка
→ статус → комментарий
→ уведомление клиенту

А технически Telegram Mini App — это что?

Здесь никакой отдельной «магической технологии Telegram» нет. В основе Mini App находится обычное веб-приложение.

Telegram
   ↓
Mini App
   ↓
HTML / CSS / JavaScript
   ↓
Frontend
   ↓
API / Backend
   ↓
База данных / CRM / внешний сервис

Frontend можно реализовать на обычном JavaScript или использовать современные библиотеки и фреймворки, например React.

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

Но если нужны:

• пользователи;
• заказы;
• личный кабинет;
• база данных;
• интеграции;
• платежи;
• работа с внешними API;
• роли и права;
• сохранение состояния;

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

Как Mini App понимает, кто его открыл

Telegram может передавать приложению данные запуска, включая информацию, необходимую для идентификации пользователя и текущей сессии. На стороне Mini App доступны данные initData.

Telegram
↓
initData
↓
Mini App
↓
Backend
↓
проверка подписи
↓
авторизованный пользователь

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

Как пользователь открывает Mini App

Mini App не обязательно запускается только одной кнопкой внутри диалога с ботом. В зависимости от конфигурации Telegram позволяет использовать разные точки входа:

• кнопку запуска в профиле бота;
• кнопку внутри сообщения;
• кнопку меню бота;
• специальную ссылку на Mini App;
• другие поддерживаемые Telegram сценарии запуска.

Для Main Mini App можно настроить отдельную кнопку запуска прямо в профиле бота. Это позволяет использовать Telegram уже не просто как чат с командами, а как точку входа в приложение.

Нужен ли для Mini App отдельный сайт

Отдельный публичный сайт пользователю обычно не нужен. Но технически Mini App является веб-приложением, поэтому его frontend всё равно должен где-то размещаться.

Telegram Bot
      ↓
Telegram Mini App
      ↓
HTTPS
      ↓
Frontend
      ↓
Backend / API
      ↓
База данных

Не все эти элементы обязательны. Простому Mini App может быть достаточно только frontend. Более сложному проекту могут понадобиться домен, HTTPS, сервер, backend, база данных, Bot API, внешний API, хранилище файлов, очередь задач и дополнительные сервисы.

Архитектуру лучше выбирать под конкретную задачу, а не строить большой backend заранее «на всякий случай».

Можно ли добавить Mini App к существующему Telegram-боту

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

Бот
├─ уведомления
├─ сообщения
├─ поддержка
└─ открыть каталог
       ↓
     Mini App

Это часто рациональнее полной переделки проекта. То же относится к существующему backend или API: если они нормально работают, Mini App можно сделать новым интерфейсом к уже существующей системе.

Можно ли подключить существующий сайт или API

Да, но здесь всё зависит от архитектуры существующего проекта.

Обычный сайт ─────┐
                  ├─ API → Backend → БД
Telegram Mini App ┘

Необязательно создавать для Telegram вторую отдельную базу и дублировать всю бизнес-логику. Иногда старое API неудобно или небезопасно использовать напрямую — тогда между Mini App и существующей системой добавляется отдельный backend-слой. Решение принимается после просмотра текущего проекта.

Когда Telegram Mini App вообще не нужен

Telegram Mini App — не универсальная замена ботам, сайтам и мобильным приложениям.

Если задача простая, Mini App может только добавить лишнюю разработку и поддержку. Например, если требуется:

• принять имя и телефон;
• отправить файл;
• сообщить статус;
• выдать ссылку;
• ответить на несколько команд;
• отправлять уведомления;
• провести пользователя через очень короткий сценарий.

обычного Telegram-бота часто вполне достаточно.

То есть сначала стоит определить задачу, а уже потом выбирать технологию.

Что может сломаться в уже работающем Mini App

Telegram Mini App — это несколько связанных компонентов, поэтому проблема не всегда находится там, где кажется.

• приложение вообще не открывается;
• показывает пустой или белый экран;
• бесконечно загружается;
• работает в обычном браузере, но ломается внутри Telegram;
• перестаёт определять пользователя;
• неправильно обрабатывает initData;
• не проходит авторизацию;
• не получает данные от backend;
• перестаёт отправлять запросы к API;
• не загружает профиль или заказы;
• перестаёт взаимодействовать с ботом;
• ломается после обновления frontend или backend;
• перестаёт работать после переноса;
• имеет проблемы с HTTPS, доменом, CRM или внешним API;
• некорректно работает только на определённых устройствах.

Сообщение «Mini App не работает» само по себе ещё мало что говорит о причине.

Telegram
↓
точка запуска
↓
Mini App frontend
↓
авторизация
↓
API
↓
backend
↓
база данных
↓
внешний сервис

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

Нужно ли переписывать сломанный Mini App с нуля

Не обязательно. Если проект уже существует, сначала полезнее понять его текущее состояние: frontend может работать, а сломаться API; backend может быть исправен, но не проходить Telegram-авторизация; запросы могут идти на старый адрес; проблема может находиться только в одной функции или интеграции.

починить существующее
или
доработать
или
переписать проблемную часть
или
только тогда делать заново

Это обычно дешевле и безопаснее, чем заранее считать весь старый проект непригодным.

Разработка и доработка Telegram Mini App

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

Нужно понять:

• кто будет пользоваться приложением;
• что пользователь должен сделать;
• какие данные он видит и меняет;
• нужен ли Telegram-бот кроме Mini App;
• нужны ли backend и база данных;
• есть ли существующий API;
• какие внешние сервисы подключаются;
• какие состояния и ошибки должны обрабатываться.

После этого уже можно проектировать интерфейс и архитектуру.

Mini App
+
бот

Если текущая архитектура позволяет развивать приложение, разумнее продолжить её, чем создавать параллельную систему.