Інлайн-бот 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, розмітка й кнопки
Як надіслати повідомлення через бота телеграм: sendMessage на curl, Python і JavaScript, parse_mode HTML і MarkdownV2, кнопки та помилки 400, 403, 429.
Токен бота Telegram: як отримати, де знайти, як перевірити й відкликати
Токен бота Телеграм: як отримати його в @BotFather, де знайти токен наявного бота, як перевірити через getMe і що робити, якщо токен витік.
Вебхук для телеграм-бота: налаштування setWebhook, перевірка та видалення
Як налаштувати вебхук телеграм-бота: вимоги до HTTPS і портів, setWebhook із secret_token, перевірка через getWebhookInfo, видалення та типові помилки.
Як дізнатися chat id у Телеграм: користувач, група, канал і тема форуму
Як дізнатися chat id у Телеграм через 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.