Включаем inline-режим и приём обновлений
В BotFather выполните /setinline, выберите бота и задайте подсказку, например «Название товара». Затем проверьте ввод @username пробел запрос в тестовом чате, где разрешена отправка такого содержимого. Разрешения конкретного чата и клиента всё равно действуют: заголовок «в любой чат» описывает способ использования, а не обход запретов Telegram.
В 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: это будет другой сценарий и другой получатель.
{
"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
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="". Отсутствие ответа выглядит как зависший поиск. При желании добавьте кнопку над результатами, ведущую в личный чат:
{
"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.