Telegram Mini App — веб-интерфейс, который запускается внутри Telegram из профиля бота, кнопки или ссылки. Например, Mini App может показать список столиков и дать пользователю выбрать столик на мероприятии. Клиент Telegram открывает интерфейс; бот и сервер твоего приложения продолжают отвечать за контекст, права и запись результата. Удобный запуск внутри мессенджера сам по себе не доказывает, кто пользователь и имеет ли он право менять конкретный заказ.
Раздели Telegram-контекст, UI и сервер
Поток выглядит так:
- Пользователь запускает Mini App из меню/кнопки или основной ссылки бота.
- Telegram открывает web UI и предоставляет объект
Telegram.WebApp. - Клиент может показать приветствие или тему, но отправляет
initDataна backend при запросе защищённого действия. - Backend проверяет подпись и свежесть данных по официальному алгоритму Telegram.
- Приложение отдельно проверяет свою авторизацию и разрешает действие: например, столик свободен и относится к нужному событию.
Telegram документирует варианты запуска Mini Apps, включая menu button и main Mini App; выбор влияет на контекст запуска и доступные параметры (Telegram Mini Apps). Перед запуском укажи, откуда пользователь входит, какие поля ожидаешь и как приложение ведёт себя, если запущено обычным браузером без Telegram.
initDataUnsafe — только для интерфейсной подсказки
Telegram.WebApp.initData — исходная строка данных, которую следует отправить серверу для проверки. initDataUnsafe — удобный разобранный объект, но Telegram прямо предупреждает не доверять его данным и использовать для серверного решения только проверенный initData (официальный раздел Initializing Mini Apps). Можно показать имя из initDataUnsafe как предварительный UI, но не выдавай по нему доступ, не меняй владельца заказа и не открывай чужие записи.
Валидация по документации Telegram не сводится к чтению user.id. Backend получает raw query string, разделяет пары ключ/значение, исключает поле hash из набора проверки, строит data-check-string из оставшихся полей в алфавитном порядке с LF-разделителем, вычисляет HMAC-SHA-256 с ключом, производным от bot token по алгоритму Telegram, и сравнивает итоговую hex-подпись с hash. Telegram также предлагает проверять auth_date, чтобы отбрасывать устаревшую передачу (Validation section). Для криптографического кода используй библиотеку и точно следуй порядку аргументов её HMAC API: обозначение в документации и сигнатура функции могут выражать key/message в разном порядке. Не печатай bot token и не отправляй его в браузер.
После успешной проверки идентичности Mini App всё равно применяет собственные роли и правила. Проверка «подпись Telegram верна» не означает «пользователь организатор мероприятия». Для изменения столика backend должен сверить пользователя, мероприятие, текущую занятость и допустимый переход состояния.
Для проверки серверного маршрута и ошибок внешнего API есть отдельное руководство по подключению API.
Как ИИ может помочь с первым срезом
Дай ограниченную задачу:
Сделай экран Mini App выбора столика для демонстрации. Используй synthetic event и test seats. Раздели UI, endpoint и проверку Telegram initData. В клиенте не считай initDataUnsafe доказательством личности. Опиши, что сервер должен отклонить: отсутствующие данные, неверную подпись, старую auth_date и попытку выбрать уже занятый столик. Не добавляй оплату и не показывай успех бронирования до ответа сервера.
Попроси отдельно описать состояния: загружается, не запущено в Telegram, данные отсутствуют, подпись не прошла, слот занят, действие сохранено. Код здесь не запускался; любая криптографическая реализация должна быть сверена с актуальным Telegram Bot API и отдельно протестирована.
Тестируй по слоям
- Запуск: menu button, основная ссылка или другой выбранный способ открывает ожидаемый экран.
- Клиент: интерфейс учитывает видимую высоту/тему Telegram, но остаётся понятным и при отсутствии части optional полей.
- Валидация: изменённый query, неверный hash и отсутствующий
auth_dateотклоняются согласно серверной политике. - Свежесть: запоздавшая подпись не принимается после выбранного окна времени.
- Авторизация: подписанный пользователь не может менять чужой заказ или ресурс вне своей роли.
- Состояние гонки: две попытки занять последний столик не обе становятся подтверждёнными.
- Ошибка: timeout backend не превращается в сообщение «успешно».
В Telegram docs поле auth_date — Unix timestamp получения данных Mini App; допустимое окно свежести определяется твоей политикой. Не переноси client-only тест в продакшен: факт, что initDataUnsafe присутствует локально, ничего не говорит о серверной проверке.
Что считать рабочим прототипом
Прототип показывает запуск и понятные состояния на фиктивных данных. Для реального бронирования нужны HTTPS endpoint, bot token на сервере, проверка initData и проверка прав на выбранную сущность. Отдельно проверяются условия публикации/доступности бота и обработка ошибок Telegram. Не описывай макет как Mini App с работающей авторизацией, пока серверный цикл не подтвердил это на валидных и изменённых примерах.