Telegram Bot API

Інлайн-бот Telegram: як увімкнути inline mode і відповідати на інлайн-запити

· 8 хв читання

Інлайн-бот Telegram відповідає на запити просто в полі введення: користувач пише @your_bot і текст у будь-якому чаті, бот отримує апдейт inline_query і відповідає методом answerInlineQuery, а користувач натискає один із результатів і надсилає його. Щоб створити такого бота, увімкніть inline mode (командою /setinline в @BotFather або, починаючи з Bot API 10.5, методом setMySettings), обробляйте апдейти inline_query і повертайте до 50 результатів. Нижче — усі кроки та повний приклад на Python і JavaScript.

Як працює інлайн-режим

Інлайн-режим працює в будь-якому чаті, навіть там, де бот не є учасником. Схема така:

  1. Користувач вводить у полі повідомлення username бота й запит, наприклад @your_bot привіт. До чату поки нічого не надсилається.
  2. Бот отримує апдейт inline_query.
  3. Бот викликає answerInlineQuery зі списком результатів: статті, фото, GIF, відео, стікери, геопозиції тощо.
  4. Користувач натискає результат. Повідомлення надсилає сам користувач, а поруч із його іменем видно username бота; у Bot API таке повідомлення має поле via_bot.
  5. За бажання бот отримує апдейт chosen_inline_result — який саме результат надіслали.

Як увімкнути inline mode для бота Telegram

У нових ботів інлайн-режим вимкнений. Якщо бота ще немає, почніть із гайду як створити бота в Telegram. Далі — один із двох способів.

Спосіб 1: @BotFather

  1. Надішліть /setinline у @BotFather і виберіть бота.
  2. Введіть текст-підказку (placeholder), який користувач побачить у полі введення після username бота, наприклад Введіть текст для форматування…
  3. За бажання: /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}'

Параметри інлайн-режиму:

Перевірити без коду: відкрийте 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_personaltrue — кешувати результати лише для цього користувача; типово їх може отримати будь-хто, хто надішле той самий запит
next_offsetЗсув, який клієнт надішле з наступним запитом із тим самим текстом; порожній рядок, якщо результатів більше немає; до 64 байтів
buttonInlineQueryResultsButton над результатами

Типи інлайн-результатів

Клієнти Telegram підтримують 20 типів результатів. Дванадцять описують новий контент (article, photo, gif, mpeg4_gif, video, audio, voice, document, location, venue, contact, game), а вісім типів InlineQueryResultCached… використовують файли, що вже зберігаються на серверах Telegram, за file_id. Кожен результат мусить мати type та id завдовжки 1–64 байти. Найуживаніші:

Усі 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, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");

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 і рівно одне з полів:

Типовий сценарій: спершу попросити користувача під'єднати акаунт, а потім надіслати інлайн-кнопку з 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.