Перейти к содержанию
12 минут чтения
Тема: Практика Mini Apps · Deep links · Telegram Bot API

Как открыть конкретный товар или заказ в Mini App по ссылке

Для примера возьмём магазин чая. Ссылку на карточку можно переслать друзьям, а из уведомления «Заказ готов» покупатель сразу переходит к своему заказу. В обоих случаях Telegram открывает одно приложение. Параметр запуска подсказывает, какой экран показать.

Добавляем URL-кнопку к уведомлению

Когда заказ готов, передайте в sendMessage сохранённый ID личного чата покупателя и URL-кнопку. В примере ниже числовой chat_id условный. Запрос отправляется с сервера. Ссылку соберите из настроенных имени бота и короткого имени приложения и проверенного публичного ID заказа.

JSON · тело запроса sendMessage
{
  "chat_id": 123456789,
  "text": "Заказ готов к выдаче.",
  "reply_markup": {
    "inline_keyboard": [
      [{
        "text": "Открыть заказ",
        "url": "https://t.me/tea_demo_bot/shop?startapp=o_6f3870e291ac4bf0a33fa8f8"
      }]
    ]
  }
}

Для карточки товара используйте такой же тип кнопки с параметром p_. У кнопки с url нажатие открывает ссылку. Обработчик callback_query для этого действия не требуется.

Выбираем экран при запуске

Для прямой ссылки Telegram передаёт значение как start_param в данных запуска и как tgWebAppStartParam для ранней настройки интерфейса. Например, по нему можно показать заголовок «Загружаем заказ» до входа. К значению из initDataUnsafe или URL относитесь как к подсказке интерфейса.

JavaScript · выбор экрана
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 аккаунта сайта, к которому он подтверждённо привязан. Возвращайте только поля, нужные для показа заказа.

SQL · выборка для авторизованного пользователя
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 раньше следующего кода.

JavaScript · запуск после загрузки страницы
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, чтобы использовать ту же сессию, что и вход. Публичный товар ниже задан массивом для воспроизводимого примера; замените его выборкой своего каталога с признаком доступности. Заказ выбирается только из БД и только для владельца.

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