TRIBLYМини-приложения
Мини-приложение — веб-страница вашего сервиса, которая открывается внутри мессенджера из чата с ботом. Модель совместима с Telegram Mini Apps, поэтому готовые мини-аппы обычно заводятся без переделки.
Настраивает мини-приложения пользователь с правом «Мини-приложения». Мини-приложение заводится у своего бота — системные боты (botmother, botai, bothr, botsupport) работают без них.
Кому открыто приложение
Круг допущенных задаётся в настройках самого приложения, списком ролей.
Роль не выбрана — приложение видят двое: тот, кто завёл бота, и владелец системы. Каждая отмеченная роль добавляет к ним своих носителей. Гость мини-приложения не открывает.
Решение принимает мессенджер, а не страница: страница видит подписанный init_data и считает вошедшего допущенным, поэтому проверять права она обычно и не умеет. Отсюда и значение по умолчанию — новое приложение открыто тому, кто его завёл.
Круг действует на всё, что делает приложение: запуск, облачное хранилище и отправку данных владельцу. Меняется он на лету — у того, кто потерял доступ, кнопка запуска пропадает без переоткрытия чата.
Настройка бота
| Метод | Путь | Назначение |
|---|---|---|
| GET | /api/v1/miniapps |
Список ботов, которым можно включить мини-приложение |
| GET/PUT | /api/v1/miniapps/:id |
Настройки: адрес страницы, включено/выключено, название, разрешённые домены, роли с доступом |
| GET | /api/v1/miniapp/:botId/launch |
Запуск: отдаёт адрес страницы и подписанный init_data |
SDK и демо
Вместе с сервером поставляются SDK и рабочее демо. Подключите SDK к своей странице:
<script src="https://<сервер>/web/sdk/messenger-app.js"></script>
<script>
MessengerApp.ready();
const user = MessengerApp.initDataUnsafe.user;
</script>
Демо лежит по адресу /web/miniapp-demo/: укажите его адресом страницы в настройках бота и посмотрите, как это работает. В SDK доступны window.MessengerApp и его алиас window.Telegram.WebApp.
Хранилище на стороне мессенджера
Мини-приложение может хранить у мессенджера небольшие данные пользователя — настройки и черновики:
| Метод | Путь | Действие |
|---|---|---|
| POST | /api/v1/miniapp/:botId/storage |
Записать пару {key, value} |
| GET | /api/v1/miniapp/:botId/storage?keys=a,b |
Прочитать (без keys — список ключей) |
| DELETE | /api/v1/miniapp/:botId/storage |
Удалить {keys:[...]} |
| POST | /api/v1/miniapp/:botId/send-data |
Отправить данные владельцу бота |
Ограничения хранилища: ключ до 128 символов, значение до 4096 байт, до 1024 ключей на пару «пользователь + бот»; разовая передача через send-data — до 4096 байт.
Проверка личности пользователя (обязательно)
Личность пользователя подтверждается подписью init_data. Проверяйте её на своём сервере: секрет есть только у него, страница подпись лишь передаёт:
secret = HMAC_SHA256(key="WebAppData", msg=токен_бота)
hash = HMAC_SHA256(key=secret, msg=строка_проверки)
где строка проверки — это отсортированные по алфавиту пары ключ=значение, соединённые переводом строки (без самого hash). Токен бота выдаёт botmother командой /token; храните его как секрет сервера. Схема совпадает с Telegram Mini Apps — подходит любая библиотека проверки Telegram-initData.
Подписанные поля:
| Поле | Содержимое |
|---|---|
user |
id, username, display_name, avatar, is_server_owner, is_bot_owner |
bot_id |
номер бота на этом сервере |
server_url |
публичный адрес сервера мессенджера |
license_number |
номер лицензии сервера — тот же, что называют в поддержке |
auth_date |
момент выдачи, unix-секунды |
query_id |
случайное значение на каждое открытие |
start_param |
параметр запуска |
После подписи проверяются три вещи: auth_date укладывается в ваше окно (для входа — 5–15 минут; мессенджер принимает init_data обратно в течение 24 часов), bot_id — бот, чьим токеном проверяли, личность — user.id.
Бэкенд, обслуживающий несколько серверов, хранит токен бота по license_number и проверяет подпись токеном того сервера, чей номер пришёл. Метка лежит внутри подписи: сходится подпись только у токена того сервера, чей номер указан.
Готовые примеры проверки на Go и Node.js — в docs/MINIAPP_INIT_DATA.md репозитория.
Доверенные origin
Поле в настройках бота действует в веб-версии мессенджера, где страница живёт во фрейме и общается с приложением через postMessage. Сообщения принимаются с origin самой страницы и с перечисленных в поле — так страница, ушедшая своим потоком входа на соседний домен владельца, продолжает говорить с приложением. Подписанные данные запуска уходят только на origin страницы.
Для страницы на адресе самого мессенджера поле остаётся пустым.
Требования к странице мини-приложения
- Разрешите встраивание страницы во фрейм политикой
Content-Security-Policy: frame-ancestors— так она открывается в веб-версии. - Работайте по HTTPS, если мессенджер работает по HTTPS; куки сессии —
SameSite=None; Secure. - Сделайте адаптивную вёрстку (
<meta name="viewport" ...>): страница открывается в узком окне. - Перечислите домены своей страницы в списке разрешённых доменов в настройках бота.
Мини-приложению доступны подписанные данные пользователя и методы хранилища из SDK.
Смежные страницы: «Боты и Bot API».