Перейти к содержанию
12 минут чтения
Тема: Практика PHP · Каталог · Inline-кнопки

Как сделать каталог товаров в Telegram-боте с кнопками «Вперёд» и «Назад»

Для примера покажем каталог услуг мастерской: пользователь выбирает категорию, видит до пяти позиций и листает их кнопками «Вперёд» и «Назад». Вместо нового сообщения на каждое нажатие будем редактировать одно меню. Сохраним категорию на сервере и отклоним кнопки от прежнего состояния каталога.

Отделяем каталог от состояния меню

Используем PHP 8.3+, 64-битные целые числа, PDO SQLite и уже настроенный обработчик webhook. Каталог содержит только текстовый список и навигацию; оформление покупки и оплата — отдельные сценарии. Клиент Telegram не хранит для сервера надёжную сессию меню, поэтому нужные сведения записываем в БД.

Таблица categories содержит id, title и version. Products содержит id, category_id, title, price_minor, is_active и sort_order. Цена хранится целым числом в копейках, все позиции примера — в рублях. Для простоты ограничьте название товара 80 символами, чтобы пять строк помещались в одно сообщение.

В catalog_sessions сохраняйте token, bot_id, user_id, chat_id, message_id, category_id, catalog_version, revision, page и expires_at. Случайный token создавайте через bin2hex(random_bytes(8)); уникальное ограничение отклоняет редкую коллизию, после которой создаётся другой token. Session действует, например, 30 минут и принадлежит одному пользователю.

Catalog_version — снимок categories.version в момент открытия меню. Увеличивайте версию категории в одной транзакции с изменением её товаров, цены, доступности и порядка. Если товар переносится в другую категорию, обновите обе версии. Так бот не показывает навигацию от уже изменённого набора данных.

Базовые правила callback описаны в руководстве о неработающих inline-кнопках. Здесь сосредоточимся на полноценном меню с состоянием, а не только на доставке нажатия.

Загружаем страницу в стабильном порядке

Сортировка должна быть определённой. Одного ORDER BY sort_order недостаточно: у двух товаров может быть одинаковый порядок. Добавляем id, считаем страницы и ограничиваем запрошенный номер допустимыми границами. Для небольшого каталога OFFSET подходит; на больших наборах стоит перейти к навигации по курсору.

Первая страница текстового каталога содержит пять товаров и кнопку Вперёд; вторая, последняя — один товар и кнопку Назад.
Первая страница текстового каталога содержит пять товаров и кнопку Вперёд; вторая, последняя — один товар и кнопку Назад.
Схема сообщений, не снимок Telegram. Текст и кнопки получены функцией catalogPage из статьи на шести вымышленных товарах; фотографий и покупки в примере нет.
PHP · catalog-page.php
<?php
declare(strict_types=1);

/** @return array{page: int, text: string, reply_markup: array<string, mixed>} */
function catalogPage(PDO $db, int $categoryId, int $requestedPage, string $token, int $revision): array
{
    $size = 5;
    $count = $db->prepare('SELECT COUNT(*) FROM products WHERE category_id = ? AND is_active = 1');
    $count->execute([$categoryId]);
    $total = (int) $count->fetchColumn();
    $pages = max(1, (int) ceil($total / $size));
    $page = max(0, min($requestedPage, $pages - 1));
    $query = $db->prepare(
        'SELECT id, title, price_minor FROM products
         WHERE category_id = :category AND is_active = 1
         ORDER BY sort_order, id LIMIT :size OFFSET :offset'
    );
    $query->bindValue(':category', $categoryId, PDO::PARAM_INT);
    $query->bindValue(':size', $size, PDO::PARAM_INT);
    $query->bindValue(':offset', $page * $size, PDO::PARAM_INT);
    $query->execute();
    $lines = ['Каталог · страница '.($page + 1).' из '.$pages];
    foreach ($query->fetchAll(PDO::FETCH_ASSOC) as $product) {
        $price = number_format((int) $product['price_minor'] / 100, 2, ',', ' ');
        $lines[] = $product['title'].' — '.$price.' ₽';
    }
    if ($total === 0) {
        $lines[] = 'В этой категории пока нет доступных позиций.';
    }
    $buttons = [];
    if ($page > 0) {
        $buttons[] = ['text' => 'Назад', 'callback_data' => 'nav:'.$token.':'.$revision.':'.($page - 1)];
    }
    if ($page + 1 < $pages) {
        $buttons[] = ['text' => 'Вперёд', 'callback_data' => 'nav:'.$token.':'.$revision.':'.($page + 1)];
    }
    return [
        'page' => $page, 'text' => implode("\n", $lines),
        'reply_markup' => ['inline_keyboard' => $buttons === [] ? [] : [$buttons]],
    ];
}

Функция возвращает данные для sendMessage или editMessageText, но сама ничего не отправляет. Служебное поле page запишите в сессию и уберите из параметров API. Parse_mode намеренно отсутствует: названия товаров не должны неожиданно интерпретироваться как HTML или Markdown.

На первой странице нет «Назад», на последней нет «Вперёд». Для пустой категории функция выдаёт понятное сообщение и пустую inline-клавиатуру. Товарные описания и фотографии лучше открывать отдельным экраном, сохранив обратный переход в ту же категорию.

Открываем категорию и связываем её с сообщением

Для выбора категории сначала отправьте меню с кнопками вида category:12. Получив callback, проверьте, что категория существует и доступна пользователю. Сам ID категории в callback не даёт права доступа; если каталог содержит закрытые цены, проверка обязательна при каждом чтении.

После выбора создайте новую catalog_sessions с page=0 и revision=1. Category_id берётся из проверенной категории, catalog_version — из её текущей версии. Случайный token нужен для ссылки на конкретное меню, а не для хранения самой категории в каждой кнопке.

Сформируйте первую страницу через catalogPage и отправьте sendMessage с chat_id, text и reply_markup. Из успешного ответа сохраните result.message_id. Пока message_id не сохранён, сессия не должна принимать навигацию: при очень быстром нажатии предложите открыть каталог заново. Ошибка сохранения связи не повод принимать кнопки от любого сообщения.

При каждом новом /catalog создавайте новую сессию и закрывайте предыдущую активную сессию пользователя для этого бота. Повторная команда не должна незаметно менять category_id старого сообщения. Если разрешаете несколько открытых меню одновременно, оставляйте им отдельные token и отдельные message_id.

Формат nav:token:revision:page укладывается в лимит callback_data 1–64 байта. Лимит считается в байтах, поэтому короткие ASCII-значения удобнее длинных русских названий и сериализованного JSON. Категория и права остаются на сервере.

Проверяем владельца, сообщение и версию кнопки

Следующая функция проверяет принадлежность callback к сохранённой сессии. Она не загружает сессию по данным клиента целиком: сначала извлеките token по такому же шаблону и найдите строку по (bot_id, token), затем передайте результат функции. currentCatalogVersion загрузите из categories по category_id найденной сессии.

PHP · catalog-callback.php
<?php
declare(strict_types=1);

/** @param array<string, mixed> $callback
 *  @param array<string, mixed> $session
 */
function requestedCatalogPage(
    array $callback, array $session, string $botId,
    int $currentCatalogVersion, int $now,
): ?int {
    $data = $callback['data'] ?? null;
    if (!is_string($data)
        || !preg_match('/\Anav:([a-f0-9]{16}):([0-9]{1,9}):([0-9]{1,6})\z/', $data, $parts)) {
        return null;
    }
    $message = $callback['message'] ?? [];
    if (($session['bot_id'] ?? null) !== $botId
        || $session['token'] !== $parts[1]
        || (int) $session['user_id'] !== ($callback['from']['id'] ?? null)
        || (int) $session['chat_id'] !== ($message['chat']['id'] ?? null)
        || (int) $session['message_id'] !== ($message['message_id'] ?? null)
        || ($message['date'] ?? 0) === 0
        || (int) $session['expires_at'] <= $now
        || (int) $session['revision'] !== (int) $parts[2]
        || (int) $session['catalog_version'] !== $currentCatalogVersion) {
        return null;
    }
    $page = (int) $parts[3];
    return abs($page - (int) $session['page']) === 1 ? $page : null;
}

Expires_at в этом примере — Unix timestamp. Cast к int нужен для значений, полученных из PDO строками; Telegram-числа из json_decode остаются целыми. Пример не поддерживает inline_message_id и недоступное исходное сообщение: в этих случаях откройте новое меню, вместо попытки угадать chat_id.

Даже если token выглядит случайным, проверяйте from.id. Иначе чужой участник группового чата сможет управлять меню пользователя. Для личного каталога это ещё и защита от ошибочной привязки сессии при повторной обработке.

На каждое нажатие вызывайте answerCallbackQuery с callback_query_id. Для отклонённого callback добавьте text «Это меню устарело. Откройте /catalog»; для принятого достаточно ответа без текста. Не ждите длительного чтения каталога или очереди, прежде чем убрать индикатор ожидания. Это отдельный метод, а не HTTP-ответ webhook.

Меняем страницу и защищаемся от двойного нажатия

Проверка callback и изменение revision должны быть согласованы. В короткой транзакции перечитайте сессию, проверьте её владельца/срок и версию категории, сформируйте страницу, затем обновите сессию условием WHERE bot_id=? AND token=? AND revision=?. Если обновлена не одна строка, другой обработчик уже забрал этот переход: не отправляйте второй edit.

Revision увеличивайте на единицу и используйте новое значение в клавиатуре, которую вернул catalogPage. Запишите фактическую page, потому что функция могла ограничить запрошенный номер границами. При достижении предела формата revision или более миллиона страниц создайте новую сессию либо измените формат с проверкой длины callback_data.

Транзакцию завершите до HTTP-запроса. После этого отправьте editMessageText с сохранёнными chat_id/message_id, новым text и reply_markup. Не добавляйте page в API-параметры и не берите category_id из callback. Не запускайте редактирование, если выборка товаров и её версия не относятся к согласованному снимку БД.

JSON · параметры editMessageText для пустой категории
{
  "chat_id": 123456789,
  "message_id": 340,
  "text": "Каталог · страница 1 из 1\nВ этой категории пока нет доступных позиций.",
  "reply_markup": {"inline_keyboard": []}
}

Если два нажатия пришли из одной старой клавиатуры, только первое изменит revision. Второе получит сообщение об устаревшем меню. Пользователь может нажать ещё раз уже на новой странице. Ключ (bot_id, update_id) дополнительно защищает от повторной доставки того же обновления.

Состояние в БД и сообщение Telegram не обновляются атомарно. Если edit завершился ошибкой или таймаутом после увеличения revision, старые кнопки могут перестать проходить проверку. Зафиксируйте проблему и предложите /catalog; не откатывайте revision вслепую после потери ответа, потому что Telegram мог уже применить новую клавиатуру.

Если нужен автоматический ремонт меню, храните желаемые text/reply_markup и состояние операции редактирования отдельно. Последовательный обработчик может восстановить именно последнее состояние, избегая перезаписи свежей страницы запоздавшим старым заданием. Для небольшого каталога повторное открытие — более простой явный путь восстановления.

Что делать при изменении товаров

Когда версия категории изменилась, отклоняйте старую кнопку и предлагайте открыть актуальный каталог. Это яснее, чем незаметно показывать другую страницу под прежними номерами. Категорию можно сохранить при повторном открытии, предварительно проверив, что она ещё существует и доступна.

Если позже добавите кнопку «Выбрать товар», передавайте стабильный product_id и проверяйте товар заново на сервере. Цена, наличие и категория могли измениться с момента показа. Нельзя принимать стоимость заказа из callback_data или считать показанную страницу резервированием товара.

Для варианта, где каталог меняется часто, допустима другая политика: пересчитать страницы и сообщить об обновлении. Но тогда задайте её явно и проверяйте соответствие выбранного товара. Код этого руководства использует строгую проверку версии и просит открыть новое меню.

Проверяем навигацию и восстановление

  • На 0, 1, 5, 6 и 11 активных товарах проверьте число страниц и крайние кнопки. Неактивные позиции не показываются.

  • Пройдите «Вперёд → Назад»: категория и стабильный порядок остаются теми же; новое сообщение при каждом нажатии не создаётся.

  • Повторите старый callback и дважды нажмите одну кнопку. Старая revision не должна переключать меню повторно.

  • Подставьте другого пользователя, chat_id, message_id, истёкшую сессию и неверный token. Ни один запрос не должен редактировать чужое меню.

  • Измените товар и версию категории. Старое меню предлагает открыть /catalog, новое показывает актуальные сведения.

  • Смоделируйте сбой editMessageText: пользователь может открыть меню заново, а журнал не утверждает, что редактирование подтвердилось.

Если Telegram-вызовы идут через BotGate, логика сессий и версий остаётся в приложении. Методы sendMessage, answerCallbackQuery и editMessageText вызываются с теми же Telegram-параметрами через API BotGate; транспорт не проверяет владельца вашего меню и актуальность товаров.

Первичные источники: InlineKeyboardButton и callback_data, CallbackQuery, answerCallbackQuery, editMessageText.