Перейти к содержанию
10 минут чтения
Тема: Практика Telegram Bot API · Inline · Каталог

Как сделать inline-бота: поиск товаров и отправка карточки в любой чат

Для примера магазин продаёт настольные лампы. Покупатель вводит @имя_бота лампа прямо в переписке, выбирает товар и отправляет собеседнику карточку со ссылкой. Здесь бот отвечает на поисковый запрос, а сообщение в выбранный чат отправляет пользователь.

Включаем inline-режим и приём обновлений

В BotFather выполните /setinline, выберите бота и задайте подсказку, например «Название товара». Затем проверьте ввод @username пробел запрос в тестовом чате, где разрешена отправка такого содержимого. Разрешения конкретного чата и клиента всё равно действуют: заголовок «в любой чат» описывает способ использования, а не обход запретов Telegram.

Ввод @имя_бота лампа, два результата поиска и отправленная карточка «Лампа Луна» за 3 900 ₽ с кнопкой открытия товара.
Ввод @имя_бота лампа, два результата поиска и отправленная карточка «Лампа Луна» за 3 900 ₽ с кнопкой открытия товара.
Схема, не снимок Telegram. Товары, цены, текст карточки и кнопка получены из PHP-примера статьи; username условный.

В allowed_updates своего webhook включите inline_query, сохранив остальные нужные типы. Бота не нужно добавлять участником каждого чата, в котором пользователь ищет товар. Inline-режим отличается от inline-кнопок под сообщением: callback_query и answerCallbackQuery относятся к нажатию кнопок, а поиск использует inline_query и answerInlineQuery.

Для примера нужен существующий обработчик проверенного webhook, PHP 8.3+ и mbstring. Если обновления не приходят, сначала проверьте доставку webhook. Через BotGate входящие события получают по webhook, а не getUpdates.

Что приходит в inline_query

Событие содержит id запроса, from отправителя, query поисковой строки и offset для следующей страницы. Поле chat_type может подсказывать тип контекста, но точного chat_id назначения у такого запроса нет. Не пытайтесь отправлять результат через sendMessage на from.id: это будет другой сценарий и другой получатель.

JSON · Сокращённое событие
{
  "update_id": 910001,
  "inline_query": {
    "id": "query-example-001",
    "from": {"id": 123456789, "is_bot": false, "first_name": "Анна"},
    "query": "лампа",
    "offset": ""
  }
}

В ответе передаётся именно inline_query.id, а не update_id. По мере набора пользователь создаёт новые запросы. Ответ старого запроса не нужно считать ответом следующего: связывайте каждую выдачу с её исходным id.

Выбираем только публичные товары

Для inline-поиска используйте отдельную публичную проекцию каталога: ID, название, краткое описание, публичная цена и ссылка. Исключите закупочную стоимость, персональные скидки, адреса заказов, скрытые товары и внутренние комментарии. Выбранная карточка окажется у собеседников и может быть переслана дальше.

is_personal ограничивает использование кэша другими запрашивающими пользователями, но не делает отправленное сообщение приватным. Не выдавайте через inline-режим личные счета и документы лишь потому, что запрос пришёл от авторизованного покупателя.

Ниже небольшой каталог прямо в PHP, чтобы показать весь поиск. В рабочем приложении замените массив запросом к публичным товарам с индексом, параметрами и устойчивой сортировкой. Не выполняйте долгую загрузку изображений или пересчёт цен на каждый введённый символ.

Формируем карточки и страницы на PHP

Функция возвращает параметры для answerInlineQuery. Она не отправляет запрос сама; вызовите метод вашим настроенным Telegram API-клиентом после проверки подлинности webhook. Пустой query показывает начало каталога. Неправильный offset возвращает пустую выдачу, а не используется как SQL или произвольный URL.

PHP · inline-products.php
<?php
declare(strict_types=1);

function inlineProducts(array $query): array
{
    if (!is_string($query['id'] ?? null) || $query['id'] === ''
        || !is_string($query['query'] ?? null)
        || !is_string($query['offset'] ?? null)) {
        throw new InvalidArgumentException('Invalid inline query');
    }
    $catalog = [
        ['id' => 'lamp-101', 'title' => 'Лампа Луна',
         'price' => '3 900 ₽', 'url' => 'https://shop.example.com/products/lamp-101'],
        ['id' => 'lamp-102', 'title' => 'Лампа Север',
         'price' => '4 500 ₽', 'url' => 'https://shop.example.com/products/lamp-102'],
        ['id' => 'stand-201', 'title' => 'Подставка для ноутбука',
         'price' => '2 100 ₽', 'url' => 'https://shop.example.com/products/stand-201'],
    ];
    $answer = ['inline_query_id' => $query['id'], 'results' => [],
        'cache_time' => 30, 'is_personal' => false, 'next_offset' => ''];
    $rawOffset = $query['offset'];
    if ($rawOffset !== '' && !preg_match('/^(0|[1-9][0-9]{0,5})$/D', $rawOffset)) {
        return $answer;
    }
    $offset = $rawOffset === '' ? 0 : (int) $rawOffset;
    $search = mb_strtolower(trim($query['query']));
    if (mb_strlen($search) > 256) {
        return $answer;
    }
    $matches = array_values(array_filter($catalog, static fn (array $product): bool =>
        $search === '' || mb_strpos(mb_strtolower($product['title']), $search) !== false));
    $pageSize = 2;
    foreach (array_slice($matches, $offset, $pageSize) as $product) {
        $answer['results'][] = [
            'type' => 'article', 'id' => $product['id'],
            'title' => $product['title'], 'description' => $product['price'],
            'input_message_content' => [
                'message_text' => $product['title']."\n".$product['price']."\n".$product['url'],
            ],
            'reply_markup' => ['inline_keyboard' => [[
                ['text' => 'Открыть товар', 'url' => $product['url']],
            ]]],
        ];
    }
    if ($offset + $pageSize < count($matches)) {
        $answer['next_offset'] = (string) ($offset + $pageSize);
    }
    return $answer;
}

Замените демонстрационные домен, товары и цены перед реальным использованием. В примере article — тип inline-результата, а не статья сайта. title и description описывают строку в выдаче; input_message_content задаёт сообщение после выбора. parse_mode не задан, поэтому текст не интерпретируется как HTML.

Два результата на странице выбраны для наглядной проверки offset. Telegram разрешает до 50 результатов в одном ответе. ID карточки должен быть непустым и уникальным в выдаче, длиной до 64 байт. Стабильный короткий ID товара удобнее случайного значения на каждый запрос.

Обрабатываем пустую выдачу и кэш

Если совпадений нет, всё равно ответьте answerInlineQuery с results=[] и next_offset="". Отсутствие ответа выглядит как зависший поиск. При желании добавьте кнопку над результатами, ведущую в личный чат:

JSON · Дополнительное поле button в answerInlineQuery
{
  "button": {
    "text": "Помочь найти товар",
    "start_parameter": "catalog_help"
  }
}

Обработчик /start catalog_help должен существовать и давать понятный следующий шаг. Не создавайте фиктивный товар «Ничего не найдено», который пользователь случайно отправит собеседнику как карточку.

cache_time=30 в примере допускает краткий кэш Telegram. Для первоначальной отладки можно поставить 0. Это не отменяет кэш вашей базы или поискового сервиса. При is_personal=false ответ должен быть одинаково публичным для всех пользователей с таким запросом. Если результат зависит от языка, страны или аккаунта, задайте is_personal=true и учитывайте те же параметры в собственном кэше.

Для большого живого каталога лучше непрозрачный курсор, связанный с запросом и стабильной сортировкой: числовое смещение при добавлении товаров может пропустить или повторить позиции. Ограничьте cursor длиной и проверяйте его на сервере; next_offset не должен превышать 64 байта.

Что происходит после выбора карточки

Ответ answerInlineQuery ещё не означает отправку карточки собеседнику. Пользователь может закрыть выдачу. Для наблюдения за выборами включают /setinlinefeedback и принимают chosen_inline_result, если он нужен вашему сценарию. Эти события не следует считать покупками или гарантированным полным счётчиком всех отправок.

Отправленная карточка хранит текст на момент выбора. Изменение цены в каталоге не обновляет автоматически старые сообщения. Перед оформлением заказа магазин должен заново проверить цену и наличие. Внутренняя аналитика поиска не должна подменять учёт заказов.

Если ответ задержался и Telegram отклонил запрос как устаревший, не отправляйте вместо него личное сообщение пользователю. Уберите причину задержки: тяжёлый поиск, очередь, внешнюю зависимость. Долгий автоматический retry мало полезен для запроса, по которому пользователь уже продолжил ввод.

Проверяем сценарий в двух аккаунтах

  • Введите пустой запрос: первые две карточки доступны, следующая страница показывает оставшийся товар без повторов.

  • Найдите «ЛАМПА» и «лампа»: выдача совпадает; неизвестное слово даёт пустой ответ.

  • Проверьте отрицательный и слишком длинный offset: функция не запускает произвольную выборку.

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

  • Измените цену и проверьте выдачу после истечения кэша; старое сообщение при этом остаётся прежним.

  • Проверьте другим аккаунтом, что в результатах нет личных данных и закрытых товаров.

Использование BotGate и источники

Через BotGate вызывайте answerInlineQuery с теми же параметрами; подпись входящего webhook проверяйте по документации сервиса. Бизнес-поиск и фильтрация каталога выполняются вашим приложением. Само подключение шлюза не включает inline-режим в BotFather.