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, разметка и кнопки

Как отправить сообщение через бота 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.