Инлайн-бот Telegram: как включить inline mode и отвечать на инлайн-запросы
Инлайн-бот Telegram отвечает на запросы прямо в поле ввода: пользователь пишет @your_bot и текст в любом чате, бот получает апдейт inline_query и отвечает методом answerInlineQuery, а пользователь нажимает на один из результатов и отправляет его. Чтобы сделать такого бота, включите inline mode (командой /setinline в @BotFather или, начиная с Bot API 10.5, методом setMySettings), обрабатывайте апдейты inline_query и возвращайте до 50 результатов. Ниже — все шаги и полный пример на Python и JavaScript.
Как работает инлайн-режим
Инлайн-режим работает в любом чате, даже там, где бота нет среди участников. Схема такая:
- Пользователь вводит в поле сообщения username бота и запрос, например
@your_bot привет. В чат пока ничего не отправляется. - Бот получает апдейт
inline_query. - Бот вызывает
answerInlineQueryсо списком результатов: статьи, фото, GIF, видео, стикеры, геопозиции и другое. - Пользователь нажимает на результат. Сообщение отправляет сам пользователь, а рядом с его именем видно username бота; в Bot API у такого сообщения есть поле
via_bot. - При желании бот получает апдейт
chosen_inline_result— какой именно результат был отправлен.
Как включить inline mode у бота Telegram
У новых ботов инлайн-режим выключен. Если бота ещё нет, начните с гайда как создать бота в Telegram. Дальше — один из двух способов.
Способ 1: @BotFather
- Отправьте
/setinlineв @BotFather и выберите бота. - Введите текст-подсказку (placeholder), который пользователь увидит в поле ввода после username бота, например Введите текст для оформления…
- По желанию:
/setinlinegeoзапрашивает геопозицию пользователя при каждом запросе,/setinlinefeedbackвключает апдейтыchosen_inline_result.
Способ 2: setMySettings (Bot API 10.5)
С Bot API 10.5 бот может сам менять свои настройки методом setMySettings. Непереданные настройки остаются без изменений:
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setMySettings" \
-H "Content-Type: application/json" \
-d '{"supports_inline_queries": true, "inline_query_placeholder": "Введите текст для оформления…", "inline_feedback_share_denominator": 1}'
Параметры инлайн-режима:
supports_inline_queries—trueвключает инлайн-режим,falseвыключает.inline_query_placeholder— текст-подсказка; пустая строка возвращает стандартную.needs_inline_query_location— запрашивать геопозицию пользователя с каждым инлайн-запросом.inline_feedback_share_denominator— получать 1 из N выбранных результатов; допустимо 1, 10, 100 или 1000, а0отключает апдейтыchosen_inline_result.
Проверить без кода: откройте setMySettings в Bot API Tester, вставьте токен и выполните запрос, затем вызовите getMe: в результате BotFullInfo есть supports_inline_queries и, если вы задали свою подсказку, inline_query_placeholder.
Апдейт inline_query
Пока пользователь печатает, бот получает объекты InlineQuery с такими полями:
| Поле | Значение |
|---|---|
id | Уникальный ID запроса; передайте его в answerInlineQuery как inline_query_id |
from | Пользователь, который ввёл запрос |
query | Текст запроса, до 256 символов; может быть пустым — тогда верните результаты по умолчанию или популярные |
offset | Смещение результатов; им управляет бот через next_offset |
chat_type | Необязательное: sender (личный чат с автором запроса), private, group, supergroup или channel; для секретных чатов обычно неизвестен |
location | Необязательное; только если бот запрашивает геопозицию |
Если передаёте allowed_updates в getUpdates или setWebhook, добавьте туда inline_query (и chosen_inline_result, если он нужен), иначе эти апдейты не придут.
Параметры answerInlineQuery
answerInlineQuery при успехе возвращает True. В одном ответе допускается не больше 50 результатов.
| Параметр | Описание |
|---|---|
inline_query_id | Обязательный. id запроса |
results | Обязательный. Массив объектов InlineQueryResult (≤ 50) |
cache_time | Максимальное время в секундах, на которое результат может кэшироваться на сервере; по умолчанию 300 |
is_personal | true — кэшировать результаты только для этого пользователя; по умолчанию их может получить любой, кто отправит тот же запрос |
next_offset | Смещение, которое клиент пришлёт со следующим запросом с тем же текстом; пустая строка, если результатов больше нет; до 64 байт |
button | InlineQueryResultsButton над результатами |
Типы инлайн-результатов
Клиенты Telegram поддерживают 20 типов результатов. Двенадцать описывают новый контент (article, photo, gif, mpeg4_gif, video, audio, voice, document, location, venue, contact, game), а восемь типов InlineQueryResultCached… используют файлы, уже хранящиеся на серверах Telegram, по file_id. У каждого результата обязательны type и id длиной 1–64 байта. Самые ходовые:
- article — обязательны
titleиinput_message_content; необязательныdescription,url,thumbnail_url,reply_markup. Содержимое обычноInputTextMessageContentсmessage_text(1–4096 символов) и необязательнымparse_mode. - photo — обязательны
photo_url(JPEG, до 5 МБ) иthumbnail_url; необязательныcaption(0–1024 символа),title,description.
Все URL в инлайн-результатах видны конечным пользователям, поэтому считайте их публичными. Правила разметки для parse_mode те же, что и при отправке сообщений через Bot API.
Пример инлайн-бота на Python и JavaScript
Бот оформляет текст запроса жирным, курсивом или моноширинным шрифтом. На пустой запрос он показывает кнопку в личный чат, где /start отвечает кнопками для возврата в инлайн-режим. Перед запуском задайте переменную окружения BOT_TOKEN.
import html
import os
import requests
TOKEN = os.environ["BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}"
def call(method, **params):
data = requests.post(f"{API}/{method}", json=params, timeout=40).json()
if not data["ok"]:
raise RuntimeError(f"{method}: {data['error_code']} {data['description']}")
return data["result"]
def article(result_id, title, text, message_html):
return {
"type": "article",
"id": result_id, # 1–64 байта, уникален в пределах одного ответа
"title": title,
"description": text[:100],
"input_message_content": {"message_text": message_html, "parse_mode": "HTML"},
}
def on_inline_query(query):
text = query["query"].strip()
if not text: # пустой запрос: без результатов, только кнопка в личный чат
call("answerInlineQuery", inline_query_id=query["id"], results=[], cache_time=5,
button={"text": "Как пользоваться ботом", "start_parameter": "help"})
return
safe = html.escape(text)
results = [
article("bold", "Жирный", text, f"<b>{safe}</b>"),
article("italic", "Курсив", text, f"<i>{safe}</i>"),
article("mono", "Моноширинный", text, f"<code>{safe}</code>"),
]
call("answerInlineQuery", inline_query_id=query["id"], results=results, cache_time=5)
def on_message(msg):
if msg.get("text", "").startswith("/start"): # в том числе "/start help" от кнопки
call("sendMessage", chat_id=msg["chat"]["id"],
text="Введите мой username и текст в любом чате, чтобы его оформить.",
reply_markup={"inline_keyboard": [[
{"text": "Попробовать здесь", "switch_inline_query_current_chat": "Привет"},
{"text": "Выбрать чат", "switch_inline_query": "Привет"},
]]})
offset = 0
while True:
updates = call("getUpdates", offset=offset, timeout=30,
allowed_updates=["message", "inline_query", "chosen_inline_result"])
for update in updates:
offset = update["update_id"] + 1
try:
if "inline_query" in update:
on_inline_query(update["inline_query"])
elif "chosen_inline_result" in update:
chosen = update["chosen_inline_result"]
print("chosen:", chosen["result_id"], "for query:", chosen["query"])
elif "message" in update:
on_message(update["message"])
except RuntimeError as err:
print(err)const TOKEN = process.env.BOT_TOKEN;
const API = `https://api.telegram.org/bot${TOKEN}`;
async function call(method, params = {}) {
const res = await fetch(`${API}/${method}`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(params),
signal: AbortSignal.timeout(40_000),
});
const data = await res.json();
if (!data.ok) throw new Error(`${method}: ${data.error_code} ${data.description}`);
return data.result;
}
const escapeHtml = (s) => s.replace(/&/g, "&").replace(/</g, "<").replace(/>/g, ">");
function article(id, title, text, messageHtml) {
return {
type: "article",
id, // 1–64 байта, уникален в пределах одного ответа
title,
description: text.slice(0, 100),
input_message_content: { message_text: messageHtml, parse_mode: "HTML" },
};
}
async function onInlineQuery(query) {
const text = query.query.trim();
if (!text) { // пустой запрос: без результатов, только кнопка в личный чат
await call("answerInlineQuery", {
inline_query_id: query.id, results: [], cache_time: 5,
button: { text: "Как пользоваться ботом", start_parameter: "help" },
});
return;
}
const safe = escapeHtml(text);
const results = [
article("bold", "Жирный", text, `<b>${safe}</b>`),
article("italic", "Курсив", text, `<i>${safe}</i>`),
article("mono", "Моноширинный", text, `<code>${safe}</code>`),
];
await call("answerInlineQuery", { inline_query_id: query.id, results, cache_time: 5 });
}
async function onMessage(msg) {
if (msg.text?.startsWith("/start")) { // в том числе "/start help" от кнопки
await call("sendMessage", {
chat_id: msg.chat.id,
text: "Введите мой username и текст в любом чате, чтобы его оформить.",
reply_markup: { inline_keyboard: [[
{ text: "Попробовать здесь", switch_inline_query_current_chat: "Привет" },
{ text: "Выбрать чат", switch_inline_query: "Привет" },
]] },
});
}
}
let offset = 0;
while (true) {
const updates = await call("getUpdates", {
offset, timeout: 30, allowed_updates: ["message", "inline_query", "chosen_inline_result"],
});
for (const update of updates) {
offset = update.update_id + 1;
try {
if (update.inline_query) await onInlineQuery(update.inline_query);
else if (update.chosen_inline_result) {
const chosen = update.chosen_inline_result;
console.log("chosen:", chosen.result_id, "for query:", chosen.query);
} else if (update.message) await onMessage(update.message);
} catch (err) {
console.error(err.message);
}
}
}JavaScript-версию сохраните как bot.mjs и запустите в Node.js 18+, затем наберите @your_bot привет в любом чате. Те же обработчики работают и с вебхуком — см. настройку вебхука Telegram-бота.
Пагинация через next_offset
Совпадений больше 50? Отдавайте страницами: в первом запросе offset пустой, а ваш next_offset вернётся, когда пользователь долистает список:
PAGE_SIZE = 20 # answerInlineQuery принимает не больше 50 результатов
def answer_page(query, items):
start = int(query["offset"] or 0) # в первом запросе offset равен ""
page = items[start:start + PAGE_SIZE]
more = start + PAGE_SIZE < len(items)
call("answerInlineQuery", inline_query_id=query["id"], results=page,
next_offset=str(start + PAGE_SIZE) if more else "") # "" = результатов больше нетconst PAGE_SIZE = 20; // answerInlineQuery принимает не больше 50 результатов
async function answerPage(query, items) {
const start = Number(query.offset || 0); // в первом запросе offset равен ""
const page = items.slice(start, start + PAGE_SIZE);
const more = start + PAGE_SIZE < items.length;
await call("answerInlineQuery", {
inline_query_id: query.id, results: page,
next_offset: more ? String(start + PAGE_SIZE) : "", // "" = результатов больше нет
});
}chosen_inline_result и обратная связь
Когда обратная связь включена, бот получает объект ChosenInlineResult с полями result_id, from, query, необязательной location и необязательным inline_message_id. Из-за кэширования популярный бот может получать больше выбранных результатов, чем реальных запросов, поэтому под нагрузкой получайте только 1/10, 1/100 или 1/1000 из них.
inline_message_id приходит, только если у отправленного сообщения есть инлайн-клавиатура. Сохраните его, чтобы позже отредактировать сообщение через editMessageText (передайте inline_message_id вместо chat_id и message_id); нажатия кнопок под этим сообщением придут как callback_query с тем же inline_message_id.
Кнопка над результатами и возврат в чат
Параметр button показывает InlineQueryResultsButton над результатами (или вместо них). У кнопки есть text и ровно одно из полей:
start_parameter— открывает личный чат с ботом и отправляет/start <параметр>; 1–64 символа, толькоA-Z,a-z,0-9,_и-.web_app— запускает Mini App, которое может вернуться в инлайн-режим методомswitchInlineQuery.
Типичный сценарий: сначала попросить пользователя подключить аккаунт, а затем прислать инлайн-кнопку с switch_inline_query (пользователь выбирает чат), switch_inline_query_current_chat (вставляет @your_bot запрос в текущий чат) или switch_inline_query_chosen_chat (выбор только среди пользователей, ботов, групп или каналов).
Частые проблемы
| Симптом | Вероятная причина и решение |
|---|---|
После ввода @your_bot ничего не происходит | Инлайн-режим не включён: используйте /setinline или setMySettings. |
Не приходят апдейты inline_query | Раньше был задан allowed_updates без inline_query (список запоминается), или активен вебхук и getUpdates возвращает 409 Conflict. |
| Показываются старые результаты | Кэш на сервере: уменьшите cache_time (по умолчанию 300 с) и используйте is_personal для персональных результатов. |
400 Bad Request: query is too old and response timeout expired or query ID is invalid | Ответ пришёл слишком поздно или с неверным ID. Отвечайте сразу, долгую работу выносите в фон. |
Нет chosen_inline_result | Обратная связь выключена: /setinlinefeedback или inline_feedback_share_denominator. |
| Фото-результаты не появляются | photo_url должен быть публичным JPEG до 5 МБ, а thumbnail_url обязателен. |
Нагруженным инлайн-ботам стоит учитывать и лимиты Telegram Bot API.
Частые вопросы
Как включить инлайн-режим у бота Telegram?
Отправьте /setinline в @BotFather, выберите бота и введите текст-подсказку. С Bot API 10.5 бот может сделать это и сам: метод setMySettings с supports_inline_queries: true (и при желании inline_query_placeholder).
Сколько результатов можно вернуть в answerInlineQuery?
Не больше 50 за один вызов. Для длинных списков отдавайте страницу и передавайте next_offset (до 64 байт): клиент вернёт его в поле offset, когда пользователь пролистает список.
Почему инлайн-результаты не меняются после правки кода?
Результаты могут кэшироваться на серверах Telegram на cache_time секунд, по умолчанию 300. Во время разработки ставьте маленький cache_time, а если результаты зависят от пользователя — is_personal: true.
Нужно ли добавлять инлайн-бота в чат?
Нет. Пользователь набирает username бота и запрос в поле ввода любого чата, бот получает апдейт inline_query, а выбранный результат отправляет сам пользователь — с пометкой бота (via_bot).
Как узнать, какой инлайн-результат отправил пользователь?
Включите обратную связь: /setinlinefeedback в @BotFather или inline_feedback_share_denominator в setMySettings (1, 10, 100 или 1000). Тогда бот будет получать апдейты chosen_inline_result с result_id и query.
Почему в chosen_inline_result нет inline_message_id?
Поле приходит, только если к отправленному сообщению прикреплена инлайн-клавиатура. Добавьте reply_markup в результат, если хотите потом редактировать сообщение или получать с него callback-запросы.
Читайте также
Как создать бота в Телеграм: от @BotFather до первого сообщения
Как создать бота в Телеграм: регистрация в @BotFather, токен, проверка через getMe, первое сообщение на curl и Python, команды и описание бота.
Как задеплоить Telegram-бота: VPS, Docker и serverless-хостинг
Как задеплоить Telegram-бота: polling или вебхук, сервис systemd на VPS, Docker, Cloudflare Workers с secret_token и чек-лист перед запуском.
Что нового в Telegram Bot API 10.0–10.5: настройки бота, виджеты, rich-сообщения, эфемерные сообщения и гостевой режим
Что нового в Telegram Bot API 10.0–10.5: setMySettings и BotFullInfo, HTML-виджеты, rich- и эфемерные сообщения, гостевой режим — с примерами.
Ошибки Telegram Bot API: что означает каждая ошибка и как её исправить
Ошибки Telegram Bot API с решениями: 400 chat not found, 403 bot was blocked by the user, 409 Conflict, 429 и retry_after. Таблица причин и код обработки.
Лимиты Telegram Bot API: сообщения в секунду, ошибка 429 и размеры файлов
Все лимиты Telegram Bot API в одном месте: сообщения в секунду, ошибка 429 и retry_after, платные рассылки, размеры файлов, длина текста и подписи.
Команды Telegram-бота: setMyCommands, области видимости и deep link для /start
Настройка команд Telegram-бота: /setcommands в @BotFather, setMyCommands с областями и языками, параметр /start в deep link и команды /cmd@bot в группах.
Клавиатуры Telegram-бота: инлайн-кнопки, callback_data и reply-клавиатура
Кнопки Telegram-бота: инлайн-клавиатура с callback_data, answerCallbackQuery, редактирование сообщения после нажатия, reply-клавиатура и ForceReply.
Интеграция n8n и Telegram: подключение бота, Telegram Trigger и отправка сообщений
Как подключить Telegram к n8n: токен бота в Access Token, вебхук Telegram Trigger по публичному HTTPS, отправка сообщений по chat id и разбор ошибок.
Как отправить сообщение через бота Telegram: sendMessage, разметка и кнопки
Как отправить сообщение через бота Telegram: sendMessage на curl, Python и JavaScript, parse_mode HTML и MarkdownV2, кнопки и ошибки 400, 403, 429.
Токен бота Telegram: как получить, где найти, как проверить и отозвать
Как получить токен бота Телеграм в @BotFather, где взять токен уже созданного бота, как проверить его через getMe и что делать, если токен утёк.
Вебхук для Telegram-бота: настройка setWebhook, проверка и удаление
Как настроить вебхук Телеграм-бота: требования к HTTPS и портам, setWebhook с secret_token, проверка через getWebhookInfo, удаление и частые ошибки.
Как узнать chat id в Telegram: пользователь, группа, канал и тема форума
Как узнать chat id в Telegram через getUpdates: личный чат, группа, супергруппа, канал и тема форума. Форматы id с -100 и что делать с пустым result.
Оплата Telegram Stars в боте: счета, pre-checkout, возвраты и подписки
Приём оплаты в Telegram Stars в боте: sendInvoice с XTR, pre_checkout_query, successful_payment, возвраты, подписки и пример на Python и JS.
Тестовый сервер Telegram: как тестировать бота в тестовом окружении
Тестовый сервер Telegram для ботов: вход в тестовое окружение, создание тестового бота, запросы к Bot API через /test/ и переключатель TEST в тестере.
Виджеты Telegram для сайта: вход через Telegram, встраивание постов, комментарии и кнопка «Поделиться»
Вход через Telegram на сайте: новый Telegram Login (OIDC), старый Login Widget с проверкой hash, встраивание постов, комментарии и кнопка «Поделиться».
TelegramWidget JavaScript API: свойства, события, коды ошибок и лимиты
Справочник TelegramWidget API: свойства, request(), события, коды ошибок, CSS-переменные, widget_query и answerWidgetQuery, а также все лимиты виджетов.
Примеры виджетов Telegram: готовый HTML и код бота на Python
Рабочие примеры виджетов Telegram с полным кодом: карточка заказа, счётчик с запросами widget_query, общий живой опрос и заглушка для превью в браузере.
Виджеты Telegram: интерактивный HTML прямо в сообщениях бота
Виджеты Telegram в Bot API 10.4: что это, как работают sendWidget, chat_data и public_data, где виджеты доступны сейчас и чем они отличаются от Mini Apps.
Тестирование Telegram Mini App: от браузера до отладки на телефоне
Тестирование Telegram Mini App по шагам: mock-режим в браузере, HTTPS-туннель для localhost, тестовая среда, DevTools на телефоне и проверка initData.