Клиент хочет записаться на услугу. В переписке он сначала выбирает филиал, потом специалиста, затем дату, возвращается к предыдущему ответу и снова спрашивает, какое время свободно. На таком пути отдельный экран может быть удобнее цепочки сообщений. В Гуси-Лебеди мы советуем начинать проект Mini App именно с подобной задачи: какое действие человеку нужно выполнить и что сейчас ему мешает.
Telegram Mini Apps, или мини-приложения в Телеграм, открывают веб-интерфейс внутри мессенджера. В статье разберём выбор формата, устройство сервиса и его приёмку на условном примере записи. Это поможет подготовить требования к разработке, а не просто согласовать красивые экраны.
Когда бизнесу нужно мини-приложение, а когда достаточно бота
Бот подходит для короткого диалога: ответить на вопрос, показать статус обращения, предложить несколько понятных действий. Мини-приложение стоит рассмотреть, когда человеку нужно одновременно видеть несколько вариантов, сравнивать их и управлять выбором. Например, фильтровать каталог или переносить запись в календаре. Если дополнительный экран только повторяет одну кнопку бота, сначала проверьте, какую проблему он решает.
Сам формат не обещает продажи и не приводит аудиторию автоматически. До разработки решите, откуда пользователи узнают о сервисе, почему откроют его и как смогут обратиться за помощью. Наличие большой платформы не заменяет этот путь.
Опишите результат до выбора технологий
Для нашей условной записи результатом будет не нажатие «Выбрать время», а подтверждённая запись в системе компании. Человек должен увидеть услугу, специалиста, дату, место и дальнейшие действия. Компания должна получить запись, с которой действительно может работать. Если сотрудники ведут расписание отдельно, заранее определите, какая система хранит актуальные свободные интервалы.
Такую потребность удобно описывать через user story и условия её выполнения. Вместо требования «сделать модное приложение» получится предметный сценарий: клиент выбирает доступное время, получает подтверждение и может проверить свою запись при следующем открытии.
Сравните этот путь с уже работающим сайтом. Если людям нужен доступ из разных каналов, не заставляйте каждого проходить через Telegram. Мини-приложение можно планировать как ещё один интерфейс сервиса. Для выбора общей модели пригодится наш разбор веб-приложения и мобильного приложения. Самостоятельное приложение, сайт и Mini App оценивают по нужному сценарию и условиям использования.
Как устроить вход и интерфейс внутри Telegram
В официальной документации Mini Apps описаны разные способы открытия, в том числе профиль бота, его меню и прямая ссылка. Возможности обмена зависят от выбранного способа. Поэтому согласуйте реальную точку входа и проверяйте именно её, а не только адрес веб-страницы в браузере.
В примере с записью ссылка на конкретного специалиста должна вести к понятному началу: кто это, какие услуги доступны и что выбрать дальше. Если переданный параметр устарел, нужен предусмотренный ответ. Лучше предложить актуальное расписание или выбор другого специалиста, чем показывать пустой экран.
Согласуйте состояния, которых нет на красивом макете
На готовом экране обычно всё заполнено: услуги загружены, время доступно, кнопка работает. В реальном сценарии данных может ещё не быть. Составьте отдельные состояния загрузки, пустого списка, ошибки и завершённой операции. Человек должен понимать, нужно ли подождать, изменить выбор или повторить действие.
Telegram рекомендует учитывать тему оформления и безопасные области экрана. Для проекта проверьте читаемость светлой и тёмной версии, положение кнопок и ввод с открытой клавиатурой. Пройдите длинное название услуги, несколько строк ошибки и возврат с предыдущего шага. Макет на одном телефоне не подтверждает работу в остальных клиентах.
При закрытии окна заранее решите судьбу ввода. Если предусмотрен черновик, объясните, что сохраняется и где его найти. Если время больше не доступно, восстановленный экран должен проверить актуальное расписание. Сохранённый выбор не равен действующей брони.
Полезное условие для приёмки: после возврата клиент видит либо подтверждённую запись, либо понятное предложение продолжить незавершённый выбор. Приложение не выдаёт черновик за готовую запись.
Что делают интерфейс, бот и сервер приложения
Для сервиса с записью разделите ответственность компонентов. Это позволяет обсуждать разработку на понятном языке: кто показывает расписание, кто решает, можно ли забронировать время, и где хранится результат. Перечень фреймворков сам по себе на эти вопросы не отвечает.
| Компонент | Роль в условном сервисе записи | Что проверить |
|---|---|---|
| Интерфейс Mini App | Показывает варианты, собирает выбор, объясняет состояние | Видимый результат совпадает с ответом сервера |
| Сервер сервиса | Проверяет пользователя, доступное время и правила записи | Нельзя создать чужую запись или занять уже недоступное время |
| Бот | Даёт согласованный вход и сообщения по сценарию | Сообщение относится к той же операции и тому же пользователю |
| Рабочая система компании | Хранит расписание и подтверждённые записи | Сотрудник видит созданную запись и её актуальный статус |
Конкретная архитектура может отличаться. Важна согласованная граница между частями, особенно при интеграции с существующей системой. При разработке веб-сервиса с интерфейсом в Telegram включите в требования обмен данными, обработку отказов и ответственность за сопровождение, а не только перечень экранов.
Вход через Telegram не заменяет права в вашем сервисе
Документация требует проверять initData на сервере перед использованием. Объект initDataUnsafe не является доверенным основанием для такого решения; также предусмотрена проверка актуальности по auth_date. Это проверка переданных данных, а не разрешение пользователю на любые операции.
Для нашего примера сервер должен отдельно определять, какие записи доступны клиенту. Переданный номер записи нельзя принимать как доказательство права её изменить. В проверочных случаях попробуйте запрос чужой записи, устаревший сеанс и изменённые входные данные. Используйте подготовленные тестовые аккаунты и ожидайте предусмотренный отказ.
Не размещайте токен бота в коде, который получает пользователь. В Bot API токен используется для авторизации запросов. Доступ к нему и другим секретам нужно организовать отдельно от публичного интерфейса и пользовательских сообщений об ошибках.
Если нужна оплата, сначала определите, что продаёте
Telegram разделяет оплату физических товаров и услуг через платёжных провайдеров и цифровых товаров и услуг через Telegram Stars. Для цифровых покупок внутри Telegram официальные правила предусматривают Stars. Не переносите платёжную схему одного типа продукта на другой.
Закрытие окна оплаты не объявляйте успешной покупкой. Согласуйте серверное подтверждение и поведение при отмене, ожидании и повторном запросе. Для цифровой выдачи документация отдельно требует получения successful_payment до передачи покупки. Тесты оплаты проводите в предусмотренной для проекта проверочной среде.
Как проверить Mini App перед запуском и передать в работу
Начните с одного полного маршрута. Откройте приложение согласованным способом, выберите услугу, создайте запись, найдите её в системе компании и снова откройте Mini App. Сравните данные на экране и у сотрудника. Снимок успешного сообщения подтверждает только сообщение; он не заменяет проверку самой записи.
Разберите ситуацию, когда ответ сервера потерялся
Представим: клиент нажал «Записаться», сервер сохранил запись, но соединение оборвалось до получения ответа. Приложение пока не знает, чем закончилась операция. Если оно предлагает начать всё заново, повтор может создать дубль. Если без проверки пишет «Всё готово», оно может сообщить об успехе там, где записи нет.
Согласуйте способ узнать состояние уже начатой операции и безопасно продолжить. Например, в проекте можно предусмотреть идентификатор запроса и проверку результата при повторном входе. Это решение архитектуры сервиса, которое нужно реализовать и испытать; Telegram не делает его автоматически за команду.
Другой важный случай: два клиента выбирают одно и то же время. В тесте должно быть видно, как система разрешает конфликт и что предлагает человеку, которому интервал уже недоступен. Проверка только последовательной записи этого не показывает.
- Повторное нажатие: результат соответствует согласованному правилу и не создаёт лишнюю операцию.
- Потеря связи: есть понятное состояние и способ проверить результат.
- Закрытие и возврат: сохранённые сведения не выдаются за актуальные без проверки.
- Недостаточно прав: чужие данные не показываются и не изменяются.
- Разные клиенты: основной путь проверен на согласованных версиях Telegram и устройствах.
Для каждого случая сохраните исходные условия, ожидаемый и фактический результат, версию клиента и сборку приложения. Отдельно отметьте сочетания, которые ещё не проверены. Нельзя распространять результат одного теста на все устройства или на будущие обновления.
В передачу включите доступы ответственных, описание интеграций, порядок обновления и восстановления, контакты поддержки. Решите, кто заметит недоступность приложения или расхождение записей и как разберёт обращение пользователя. Стоимость и сроки оценивайте по этому составу работ: конструктор, небольшой интерфейс и сервис с интеграциями требуют разных решений.
В Гуси-Лебеди мы советуем принимать мини-приложение по завершённому действию клиента и подтверждённому результату в компании. Тогда разговор о Mini Apps становится предметным: что человеку стало удобнее делать, где хранится результат и как сервис ведёт себя, когда что-то пошло не по плану.