Составляем ссылку с параметром startapp
Если у бота настроено именованное Mini App, укажите имя бота и короткое имя приложения. Для настроенного Main Mini App укажите только имя бота. В примере tea_demo_bot и shop нужно заменить своими значениями.
https://t.me/tea_demo_bot/shop?startapp=p_green-tea https://t.me/tea_demo_bot/shop?startapp=o_6f3870e291ac4bf0a33fa8f8 https://t.me/tea_demo_bot?startapp=p_green-tea
Префикс p_ указывает на публичный товар, o_ — на заказ. Договоримся, что у товара короткий slug, а у заказа случайный публичный ID. Для этой схемы достаточно латинских букв в нижнем регистре, цифр, дефиса и подчёркивания. Храните публичный ID заказа с ограничением уникальности. В ссылку помещайте только этот ID. Телефон, адрес, номер сессии и служебные токены в ней легко переслать вместе с сообщением.
Параметр start относится к запуску диалога с ботом и обрабатывается как команда /start. Для перехода внутри Mini App используйте startapp. Если вместо приложения открывается профиль или чат, проверьте, какой тип приложения настроен и правильно ли указано его короткое имя.
Выбираем экран при запуске
Для прямой ссылки Telegram передаёт значение как start_param в данных запуска и как tgWebAppStartParam для ранней настройки интерфейса. Например, по нему можно показать заголовок «Загружаем заказ» до входа. К значению из initDataUnsafe или URL относитесь как к подсказке интерфейса.
function parseLaunchTarget(value) {
if (typeof value !== 'string') return { screen: 'catalog' };
const product = /^p_([a-z0-9]+(?:-[a-z0-9]+)*)$/.exec(value);
if (product && product[0] === value && product[1].length <= 48) {
return { screen: 'product', id: product[1] };
}
const order = /^o_([a-f0-9]{24})$/.exec(value);
if (order && order[0] === value) {
return { screen: 'order', id: order[1] };
}
return { screen: 'catalog' };
}
const target = parseLaunchTarget(
window.Telegram?.WebApp?.initDataUnsafe?.start_param
);
Подключите скрипт Telegram перед этим кодом. Маршрутизатор приложения получает один из трёх экранов. Для товара он запрашивает публичную карточку по slug. Для заказа он дожидается серверной сессии и запрашивает детали по ID. Для пустого или некорректного параметра открывается каталог. Валидная ссылка на снятый с продажи товар показывает сообщение «Товар недоступен» и предлагает вернуться в каталог.
Если сервер сам использует start_param, извлеките его из проверенной строки initData по правилам авторизации Mini App. Даже в подписанных данных параметр отражает ссылку, по которой перешёл пользователь. Проверка подписи подтверждает личность, а право открыть конкретный заказ проверяется отдельно.
Проверяем владельца заказа на сервере
Обработчик GET /api/orders/{public_id} получает владельца из сессии. После входа по initData это может быть проверенный Telegram ID либо ID аккаунта сайта, к которому он подтверждённо привязан. Возвращайте только поля, нужные для показа заказа.
SELECT public_id, status, total_minor FROM orders WHERE public_id = :public_id AND telegram_user_id = :session_telegram_user_id;
Передавайте параметры через подготовленный запрос. Без сессии верните 401. Для чужого и отсутствующего заказа верните одинаковый 404. У защищённых ответов установите Cache-Control: private, no-store. Ту же проверку владельца примените к деталям, действиям с заказом и скачиванию документов.
Если ссылку перешлют, у получателя откроется Mini App. Его сессия подтвердит другой аккаунт, и сервер не выдаст заказ. Случайный ID снижает возможность перебора, а ограничение выборки по владельцу защищает саму запись. Про её создание и сохранение цены читайте в руководстве по оформлению заказа.
Загружаем и показываем выбранный экран
Соединим маршрутизатор с запросами. Для примера используем Laravel, вход loginMiniApp() из статьи об авторизации и таблицу orders из примера корзины. В ней есть public_id, telegram_user_id, status и total_minor. Добавьте <main id="screen" aria-live="polite"></main> на Blade-страницу. Подключите функцию входа и parseLaunchTarget раньше следующего кода.
async function showLaunchScreen(target = parseLaunchTarget(window.Telegram?.WebApp?.initDataUnsafe?.start_param)) {
const screen = document.querySelector('#screen');
screen.replaceChildren();
const title = document.createElement('h1');
const details = document.createElement('p');
screen.append(title, details);
try {
if (target.screen === 'catalog') {
title.textContent = 'Каталог';
details.textContent = 'Выберите товар в каталоге магазина.';
return;
}
title.textContent = target.screen === 'order' ? 'Загружаем заказ' : 'Загружаем товар';
if (target.screen === 'order') await loginMiniApp();
const url = target.screen === 'order' ? '/mini/orders/' : '/mini/products/';
const response = await fetch(url + encodeURIComponent(target.id), {
credentials: 'same-origin', headers: {'Accept': 'application/json'}, cache: 'no-store'
});
if (response.status === 404) {
title.textContent = 'Данные недоступны';
details.textContent = 'Проверьте ссылку или вернитесь в каталог.';
return;
}
if (response.status === 401) throw new Error('Переоткройте приложение для входа');
if (!response.ok) throw new Error('Не удалось загрузить данные. Повторите позже');
const data = await response.json();
const money = new Intl.NumberFormat('ru-RU', {style: 'currency', currency: 'RUB'});
title.textContent = target.screen === 'order' ? 'Заказ ' + data.public_id : data.title;
details.textContent = target.screen === 'order'
? 'Статус: ' + data.status + '. Сумма: ' + money.format(data.total_minor / 100)
: money.format(data.price_minor / 100);
} catch (error) {
title.textContent = 'Не удалось открыть экран';
details.textContent = error instanceof Error ? error.message : 'Повторите открытие';
} finally {
if (target.screen !== 'catalog') {
const back = document.createElement('button');
back.type = 'button';
back.textContent = 'Вернуться в каталог';
back.addEventListener('click', () => showLaunchScreen({screen: 'catalog'}));
screen.append(back);
}
window.Telegram?.WebApp?.ready();
}
}
showLaunchScreen();
Серверные маршруты находятся в routes/web.php, чтобы использовать ту же сессию, что и вход. Публичный товар ниже задан массивом для воспроизводимого примера; замените его выборкой своего каталога с признаком доступности. Заказ выбирается только из БД и только для владельца.
use Illuminate\Http\Request;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Route;
Route::get('/mini/products/{slug}', function (string $slug) {
$catalog = ['green-tea' => ['title' => 'Зелёный чай', 'price_minor' => 45000]];
abort_unless(isset($catalog[$slug]), 404);
return response()->json($catalog[$slug]);
})->where('slug', '[a-z0-9-]{1,48}')->middleware('throttle:60,1');
Route::get('/mini/orders/{id}', function (Request $request, string $id) {
$owner = $request->session()->get('mini_user_id');
abort_unless(is_int($owner) && (int) $request->session()->get('mini_expires_at', 0) > time(), 401);
$order = DB::table('orders')->where('public_id', $id)->where('telegram_user_id', $owner)
->first(['public_id', 'status', 'total_minor']);
abort_if(!$order, 404);
return response()->json($order)->header('Cache-Control', 'private, no-store');
})->where('id', '[a-f0-9]{24}')->middleware('throttle:60,1');
В этом примере используется префикс /mini, а не условный /api из описания выше. Вызовы относятся к одному origin. Для ошибок 401 и 404 также отключите кэширование на уровне вашего приложения или reverse proxy. Если установлен service worker, исключите защищённые маршруты из его кэша. Текст с сервера выводится через textContent: название товара не превращается в исполняемый HTML.
Замените ID заказа в ссылке на public_id реального тестового заказа. Откройте её покупателем и другим аккаунтом, затем повторите с истёкшей сессией. Проверяйте и интерфейс, и ответ /mini/orders: скрыть карточку только в JavaScript недостаточно. Для списка позиций добавьте отдельную выборку после проверки владельца или связь с уже найденным заказом.
Проверяем ссылки и доступ
Откройте ссылку на товар из сообщения. Должна открыться нужная карточка. Уберите параметр или задайте неизвестный префикс — должен открыться каталог.
Откройте кнопку «Открыть заказ» под аккаунтом покупателя. Статус на экране должен совпасть с серверным.
Перешлите сообщение другому тестовому аккаунту и отдельно вызовите API из его сессии с тем же ID. Заказ должен оставаться недоступным в обоих случаях.
Откройте URL страницы приложения напрямую в браузере. Без сессии запрос к заказу должен потребовать вход. Сам параметр запуска может подсказать экран, но данных заказа не откроет.
Прямые ссылки Telegram Mini Apps · Форматы ссылок Telegram · Кнопки InlineKeyboardButton