InlineQuery

InlineQuery — это функция в мессенджере Telegram, позволяющая пользователю отправлять сообщения в любой чат напрямую из поля ввода, не открывая диалог с ботом-отправителем. Для этого пользователь вводит имя бота (его @username) и через пробел — поисковый запрос. Бот обрабатывает запрос и возвращает список результатов, из которых пользователь выбирает нужный и отправляет его в текущий чат. InlineQuery реализована через Bot API и доступна для всех ботов, у которых включён соответствующий режим.

Принцип работы

InlineQuery активируется, когда пользователь вводит в любом чате (личном, групповом, канале) символ @, за которым следует имя бота, и затем пробел и текст запроса. Telegram отправляет этот запрос боту через Bot API в виде объекта InlineQuery. Бот должен ответить массивом объектов InlineQueryResult, каждый из которых описывает один вариант ответа (текст, фото, видео, ссылка, опрос и т. д.). Пользователь видит эти варианты в виде списка под полем ввода и может выбрать один, отправив его в чат.

Основные параметры InlineQuery

• query — строка запроса, введённая пользователем после имени бота.
• offset — строка, используемая для пагинации (если результатов много, бот может вернуть следующую порцию по этому смещению).
• user_id — идентификатор пользователя, отправившего запрос.
• chat_type — тип чата, в котором был сделан запрос (например, private, group, supergroup, channel).

Ответ бота

Бот должен ответить вызовом метода answerInlineQuery, передав массив результатов. Каждый результат имеет тип (например, article, photo, video, audio, voice, document, sticker, gif, mpeg4_gif, location, venue, contact, game) и уникальный строковый идентификатор. Для текстового результата (article) обязательно указывается заголовок и, опционально, описание, текст сообщения, кнопки и т. д.

История и развитие

InlineQuery была представлена в Telegram Bot API в версии 2.0 (апрель 2016 года). До этого боты могли отвечать только на команды в диалогах с ними. Новая функция позволила ботам интегрироваться в любой чат без необходимости добавлять их в группу или писать им лично. Это значительно расширило возможности автоматизации: пользователи могли, например, искать изображения, получать переводы, проверять орфографию, генерировать случайные числа и многое другое, не покидая текущего чата.

В последующих версиях API (3.0, 4.0, 5.0 и далее) были добавлены новые типы результатов (например, game, location, venue, contact), поддержка кнопок и клавиатур, а также возможность указывать switch_pm_text и switch_pm_parameter для перехода в личный чат с ботом.

Типы результатов InlineQuery

Бот может возвращать результаты разных типов. Наиболее распространённые:

• article — текстовое сообщение (может содержать Markdown или HTML-разметку, кнопки, вложения).
• photo — фотография (с указанием URL или file_id).
• video — видеофайл.
• audio — аудиофайл (например, музыка).
• voice — голосовое сообщение.
• document — любой документ.
• sticker — стикер.
• gif — анимированное изображение (GIF).
• mpeg4_gif — анимированное видео (MPEG4).
• location — точка на карте.
• venue — место (организация) с адресом и координатами.
• contact — контакт (имя, номер телефона).
• game — HTML5-игра (с возможностью отправки счёта).

Каждый тип имеет свои обязательные и опциональные поля. Например, для article обязательно указать id, title, input_message_content (объект, описывающий само сообщение). Для photo — id, photo_url, thumb_url и input_message_content.

Применение InlineQuery

InlineQuery используется в тысячах ботов Telegram. Основные сценарии:

• Поиск и отправка контента: боты-поисковики изображений (например, @pic), музыки (@vkmusic_bot), видео (@youtube), гифок (@gif).
• Перевод и проверка текста: боты-переводчики (@translatebot), проверка орфографии (@grammar_bot).
• Генерация случайных данных: пароли, числа, никнеймы, шутки, цитаты.
• Интеграция с внешними сервисами: поиск товаров (@aliexpressbot), погода (@weatherbot), курсы валют (@cbrfbot).
• Утилиты: создание QR-кодов (@qr_bot), сокращение ссылок (@LinkShortenerBot), таймеры и напоминания.
• Игры: отправка HTML5-игр прямо в чат (@gamebot).
• Образование: словари, энциклопедии, тесты.

Особенности и ограничения

• Кэширование: Telegram может кэшировать результаты InlineQuery для одного пользователя и одного запроса. Бот может указать cache_time (в секундах) для управления кэшем.
• Пагинация: при большом количестве результатов бот должен использовать next_offset для постраничной выдачи. Telegram отображает до 50 результатов на одной странице.
• Лимит на длину запроса: максимальная длина строки query — 256 символов.
• Лимит на количество результатов: в одном ответе можно вернуть до 50 результатов.
• Лимит на размер данных: суммарный размер всех результатов в одном ответе не должен превышать 10 МБ.
• Требование к скорости: бот должен ответить на InlineQuery в течение 30 секунд, иначе запрос будет считаться просроченным.
• Приватность: бот не видит содержимое чата, в котором был сделан запрос, — только сам запрос, идентификатор пользователя и тип чата.

Пример реализации (упрощённый)

Ниже приведён пример кода на Python с использованием библиотеки python-telegram-bot, демонстрирующий обработку InlineQuery и возврат двух текстовых результатов:

```python from telegram import Update, InlineQueryResultArticle, InputTextMessageContent from telegram.ext import Application, InlineQueryHandler, CommandHandler

async def inline_query(update: Update, context): query = update.inline_query.query if not query: return results = [ InlineQueryResultArticle( id='1', title='Результат 1', input_message_content=InputTextMessageContent(f'Вы ввели: {query}') ), InlineQueryResultArticle( id='2', title='Результат 2', input_message_content=InputTextMessageContent(f'Эхо: {query}') ) ] await update.inline_query.answer(results)

def main(): app = Application.builder().token('YOUR_TOKEN').build() app.add_handler(InlineQueryHandler(inline_query)) app.run_polling()

if __name__ == '__main__': main() ```

Сравнение с другими способами взаимодействия

• Команды в личном чате: пользователь пишет боту напрямую, бот отвечает в том же диалоге. InlineQuery позволяет отправлять результат в любой другой чат.
• Клавиатуры и кнопки: бот может предложить пользователю выбор, но это требует открытия диалога с ботом. InlineQuery даёт возможность выбирать и отправлять результат без переключения контекста.
• Webhook-уведомления: бот может отправлять сообщения пользователю по инициативе сервера, но не может вставлять их в произвольный чат без участия пользователя.

Критика и ограничения

• Сложность реализации: для создания качественного InlineQuery-бота требуется обработка запросов в реальном времени, часто с внешними API, что увеличивает нагрузку и время ответа.
• Ограниченная видимость: пользователь видит только первые 50 результатов, и если бот не поддерживает пагинацию, многие варианты могут быть недоступны.
• Зависимость от интернет-соединения: бот должен быть онлайн и отвечать быстро, иначе пользователь увидит пустой список.
• Отсутствие контекста: бот не знает, о чём идёт речь в чате, и не может адаптировать результаты под текущий диалог (кроме как по типу чата).

Источники

• Telegram Bot API Documentation — раздел «Inline mode»
• Библиотека python-telegram-bot — документация по InlineQueryHandler
• Статья «Telegram Bot API: Inline mode» на Habr (2016)
• Официальный бот @BotFather — описание настроек Inline mode