Telegram Bot API

Bot inline de Telegram: cómo activar el modo inline y responder consultas

· 8 min de lectura

Un bot inline de Telegram responde a consultas escritas directamente en el campo de mensaje: el usuario escribe @tu_bot y un texto en cualquier chat, tu bot recibe una actualización inline_query, contesta con answerInlineQuery y el usuario toca uno de los resultados para enviarlo. Para lograrlo, activa el modo inline (con /setinline en @BotFather o, desde Bot API 10.5, con setMySettings), procesa las actualizaciones inline_query y devuelve hasta 50 resultados. Abajo tienes cada paso y un ejemplo completo en Python y JavaScript.

Cómo funciona el modo inline

El modo inline funciona en cualquier chat, incluso donde el bot no es miembro. El flujo es este:

  1. El usuario escribe el username del bot y una consulta en el campo de texto, por ejemplo @tu_bot hola. Todavía no se envía nada al chat.
  2. El bot recibe una actualización inline_query.
  3. El bot llama a answerInlineQuery con una lista de resultados: artículos, fotos, GIFs, videos, stickers, ubicaciones y más.
  4. El usuario toca un resultado. El mensaje lo envía el usuario y junto a su nombre aparece el username del bot; en la Bot API ese mensaje trae el campo via_bot.
  5. Opcionalmente, el bot recibe una actualización chosen_inline_result que indica qué resultado se envió.

Activar el modo inline en tu bot de Telegram

En los bots nuevos el modo inline viene desactivado. Si aún no tienes bot, empieza por cómo crear un bot en Telegram. Después elige una de estas dos opciones.

Opción 1: @BotFather

  1. Envía /setinline a @BotFather y elige tu bot.
  2. Escribe el placeholder que verán los usuarios en el campo de texto tras escribir el username del bot, por ejemplo Escribe un texto para darle formato…
  3. Opcional: /setinlinegeo pide la ubicación del usuario con cada consulta; /setinlinefeedback activa las actualizaciones chosen_inline_result.

Opción 2: setMySettings (Bot API 10.5)

Desde Bot API 10.5 un bot puede cambiar su propia configuración con setMySettings. Los ajustes que no envíes se quedan como están:

curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setMySettings" \
  -H "Content-Type: application/json" \
  -d '{"supports_inline_queries": true, "inline_query_placeholder": "Escribe un texto para darle formato…", "inline_feedback_share_denominator": 1}'

Los parámetros relacionados con el modo inline son:

Para comprobarlo sin escribir código, abre setMySettings en Bot API Tester, pega tu token y ejecútalo; luego llama a getMe: su resultado BotFullInfo incluye supports_inline_queries y, si definiste uno propio, inline_query_placeholder.

La actualización inline_query

Mientras el usuario escribe, el bot recibe objetos InlineQuery con estos campos:

CampoSignificado
idID único de la consulta; pásalo a answerInlineQuery como inline_query_id
fromEl usuario que escribió la consulta
queryTexto de la consulta, hasta 256 caracteres; puede venir vacío, y entonces conviene devolver resultados por defecto o populares
offsetDesplazamiento de los resultados que hay que devolver; lo controla tu bot mediante next_offset
chat_typeOpcional: sender (chat privado con quien envía la consulta), private, group, supergroup o channel; en chats secretos normalmente se desconoce
locationOpcional; solo si el bot pide la ubicación del usuario

Si pasas allowed_updates a getUpdates o setWebhook, incluye inline_query (y chosen_inline_result si lo necesitas); de lo contrario, esas actualizaciones no llegarán.

Parámetros de answerInlineQuery

answerInlineQuery devuelve True si todo sale bien. Se permiten como máximo 50 resultados por consulta.

ParámetroDescripción
inline_query_idObligatorio. El id de la consulta
resultsObligatorio. Arreglo de objetos InlineQueryResult (≤ 50)
cache_timeTiempo máximo, en segundos, que el resultado puede quedar en caché en el servidor; 300 por defecto
is_personaltrue guarda la caché solo para este usuario; por defecto, cualquier usuario que envíe la misma consulta puede recibirlos
next_offsetOffset que el cliente enviará con la siguiente consulta del mismo texto; cadena vacía si no hay más resultados; hasta 64 bytes
buttonInlineQueryResultsButton que se muestra encima de los resultados

Tipos de resultados inline

Los clientes de Telegram admiten 20 tipos de resultado. Doce describen contenido nuevo (article, photo, gif, mpeg4_gif, video, audio, voice, document, location, venue, contact, game) y ocho tipos InlineQueryResultCached… reutilizan archivos ya guardados en los servidores de Telegram mediante file_id. Cada resultado necesita un type y un id de 1 a 64 bytes. Los más usados:

Todas las URL de los resultados inline quedan visibles para los usuarios, así que trátalas como públicas. Las reglas de formato de parse_mode son las mismas que al enviar mensajes con la Bot API.

Ejemplo: un bot inline en Python y JavaScript

Este bot devuelve la consulta en negrita, cursiva o monoespaciado. Con una consulta vacía muestra un botón hacia el chat privado, donde /start responde con botones que regresan al modo inline. Define la variable de entorno BOT_TOKEN antes de ejecutarlo.

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 bytes, único dentro de una respuesta
        "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:  # consulta vacía: sin resultados, solo un botón que abre el chat privado
        call("answerInlineQuery", inline_query_id=query["id"], results=[], cache_time=5,
             button={"text": "Cómo usar este bot", "start_parameter": "help"})
        return
    safe = html.escape(text)
    results = [
        article("bold", "Negrita", text, f"<b>{safe}</b>"),
        article("italic", "Cursiva", text, f"<i>{safe}</i>"),
        article("mono", "Monoespaciado", 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"):  # también "/start help" desde el botón
        call("sendMessage", chat_id=msg["chat"]["id"],
             text="Escribe mi username y un texto en cualquier chat para darle formato.",
             reply_markup={"inline_keyboard": [[
                 {"text": "Probar aquí", "switch_inline_query_current_chat": "Hola"},
                 {"text": "Elegir un chat", "switch_inline_query": "Hola"},
             ]]})


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("elegido:", chosen["result_id"], "para la consulta:", 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 bytes, único dentro de una respuesta
    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) { // consulta vacía: sin resultados, solo un botón que abre el chat privado
    await call("answerInlineQuery", {
      inline_query_id: query.id, results: [], cache_time: 5,
      button: { text: "Cómo usar este bot", start_parameter: "help" },
    });
    return;
  }
  const safe = escapeHtml(text);
  const results = [
    article("bold", "Negrita", text, `<b>${safe}</b>`),
    article("italic", "Cursiva", text, `<i>${safe}</i>`),
    article("mono", "Monoespaciado", 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")) { // también "/start help" desde el botón
    await call("sendMessage", {
      chat_id: msg.chat.id,
      text: "Escribe mi username y un texto en cualquier chat para darle formato.",
      reply_markup: { inline_keyboard: [[
        { text: "Probar aquí", switch_inline_query_current_chat: "Hola" },
        { text: "Elegir un chat", switch_inline_query: "Hola" },
      ]] },
    });
  }
}

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("elegido:", chosen.result_id, "para la consulta:", chosen.query);
      } else if (update.message) await onMessage(update.message);
    } catch (err) {
      console.error(err.message);
    }
  }
}

Guarda la versión de JavaScript como bot.mjs y ejecútala con Node.js 18+; luego escribe @tu_bot hola en cualquier chat. Los mismos handlers sirven con un webhook: consulta cómo configurar el webhook de un bot de Telegram.

Paginación con next_offset

¿Más de 50 coincidencias? Devuelve páginas: en la primera petición offset viene vacío, y tu next_offset regresa cuando el usuario baja en la lista:

PAGE_SIZE = 20  # answerInlineQuery acepta como máximo 50 resultados


def answer_page(query, items):
    start = int(query["offset"] or 0)  # offset es "" en la primera petición
    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 "")  # "" = no hay más resultados
const PAGE_SIZE = 20; // answerInlineQuery acepta como máximo 50 resultados

async function answerPage(query, items) {
  const start = Number(query.offset || 0); // offset es "" en la primera petición
  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) : "", // "" = no hay más resultados
  });
}

chosen_inline_result y feedback inline

Con el feedback activado, el bot recibe un objeto ChosenInlineResult con result_id, from, query, location opcional e inline_message_id opcional. Por la caché, los bots populares pueden recibir más resultados elegidos que consultas reales, así que con mucha carga conviene recibir solo 1/10, 1/100 o 1/1000 de ellos.

inline_message_id solo aparece si el mensaje enviado tiene teclado inline. Guárdalo para editar el mensaje más tarde con editMessageText (pasa inline_message_id en lugar de chat_id y message_id); las pulsaciones de botones en ese mensaje llegan como callback_query con el mismo inline_message_id.

Botón sobre los resultados y regreso al chat

El parámetro button muestra un InlineQueryResultsButton encima de los resultados (o en su lugar). Tiene un text y exactamente uno de estos campos:

Uso típico: pedir al usuario que primero vincule una cuenta y luego enviarle un botón de teclado inline con switch_inline_query (el usuario elige un chat), switch_inline_query_current_chat (inserta @tu_bot consulta en el chat actual) o switch_inline_query_chosen_chat (limita la elección a usuarios, bots, grupos o canales).

Solución de problemas

SíntomaCausa probable y solución
No pasa nada al escribir @tu_botEl modo inline no está activado: usa /setinline o setMySettings.
No llegan actualizaciones inline_queryAntes se configuró allowed_updates sin inline_query (la lista se recuerda) o hay un webhook activo y getUpdates devuelve 409 Conflict.
Siguen apareciendo resultados viejosCaché del servidor: baja cache_time (300 s por defecto) y usa is_personal para resultados por usuario.
400 Bad Request: query is too old and response timeout expired or query ID is invalidLa respuesta llegó tarde o con un ID incorrecto. Responde de inmediato y haz el trabajo pesado en segundo plano.
No llega chosen_inline_resultEl feedback inline está desactivado: /setinlinefeedback o inline_feedback_share_denominator.
Los resultados con foto no aparecenphoto_url debe ser un JPEG público de hasta 5 MB, y thumbnail_url es obligatorio.

Los bots inline con mucho tráfico también deben respetar los límites de la Telegram Bot API.

Preguntas frecuentes

¿Cómo activo el modo inline en un bot de Telegram?

Envía /setinline a @BotFather, elige el bot y escribe el texto del placeholder. Desde Bot API 10.5 el propio bot también puede hacerlo con setMySettings y supports_inline_queries: true (más un inline_query_placeholder opcional).

¿Cuántos resultados puede devolver answerInlineQuery?

Como máximo 50 por llamada. Para listas más largas, devuelve una página y pasa next_offset (hasta 64 bytes); el cliente lo reenvía en offset cuando el usuario hace scroll.

¿Por qué mis resultados inline no cambian después de actualizar el código?

Telegram puede guardar los resultados en caché durante cache_time segundos, 300 por defecto. Usa un cache_time bajo mientras desarrollas e is_personal: true si los resultados dependen del usuario.

¿Hay que agregar el bot inline al chat?

No. El usuario escribe el username del bot y una consulta en el campo de texto de cualquier chat; el bot recibe un inline_query y el resultado elegido lo envía el usuario, marcado con el username del bot (via_bot).

¿Cómo sé qué resultado inline envió el usuario?

Activa el feedback inline con /setinlinefeedback en @BotFather o con inline_feedback_share_denominator en setMySettings (1, 10, 100 o 1000). El bot recibirá actualizaciones chosen_inline_result con result_id y query.

¿Por qué falta inline_message_id en chosen_inline_result?

Solo aparece si el mensaje enviado lleva un teclado inline. Agrega reply_markup al resultado si quieres editar el mensaje después o recibir callback queries desde él.

Cómo crear un bot en Telegram paso a paso: de BotFather a tu primer mensaje

Aprende a crear un bot de Telegram: /newbot en @BotFather, token, prueba con getMe y tu primer mensaje con curl y Python. Gratis y sin servidor.

Cómo desplegar un bot de Telegram: VPS, Docker y hosting serverless

Cómo desplegar un bot de Telegram: polling o webhook, servicio systemd en un VPS, Docker, Cloudflare Workers con secret_token y checklist de lanzamiento.

Telegram Bot API 10.0–10.5: ajustes del bot, widgets, rich messages, mensajes efímeros, modo invitado y más

Qué hay de nuevo en Telegram Bot API 10.0–10.5: setMySettings y BotFullInfo, widgets HTML, mensajes rich y efímeros, modo invitado, con ejemplos JSON.

Errores de la Telegram Bot API: qué significa cada uno y cómo solucionarlo

Errores de la Telegram Bot API: 400 chat not found, 403 bot was blocked by the user, 409 Conflict y 429 retry_after. Causas, soluciones y código de manejo.

Límites de la Telegram Bot API: rate limit, error 429, tamaño de archivos y de mensajes

Límites de la Telegram Bot API: 30 msg/s, 1 msg/s por chat, 20/min en grupos, cómo manejar 429 con retry_after y límites de tamaño de archivo y de texto.

Comandos de un bot de Telegram: setMyCommands, scopes y deep links con /start

Configura los comandos de tu bot de Telegram: /setcommands en @BotFather, setMyCommands con scopes e idiomas, parámetro de /start y /cmd@bot en grupos.

Teclados de bots de Telegram: teclado inline, botones callback y reply keyboard

Agrega botones a tu bot de Telegram: teclado inline con callback_data, answerCallbackQuery, editar el mensaje tras cada clic, reply keyboard y ForceReply.

Integración de n8n con Telegram: conecta tu bot, dispara flujos y envía mensajes

Integra n8n con Telegram: token del bot como Access Token, webhook del Telegram Trigger por HTTPS, envío de mensajes por chat id y errores comunes.

Cómo enviar mensajes con la API de Telegram: sendMessage paso a paso

Envía mensajes con la Bot API de Telegram: sendMessage con curl, Python y JavaScript, formato HTML y MarkdownV2, botones inline y errores 400, 403 y 429.

Cómo obtener el token de un bot de Telegram (y qué hacer si se filtra)

Cómo obtener el token de tu bot de Telegram con @BotFather, encontrarlo si el bot ya existe, comprobarlo con getMe y revocarlo si se filtró.

Webhook de Telegram: cómo configurar setWebhook para tu bot (Python y n8n)

Configura el webhook de tu bot de Telegram: requisitos HTTPS, setWebhook con secret_token, getWebhookInfo, handler en Python y errores típicos en n8n.

Cómo obtener el chat id de Telegram: usuarios, grupos, canales y temas

Obtén el chat id de Telegram para tu bot con getUpdates: usuarios, grupos, supergrupos (-100…), canales y temas, y qué hacer si result viene vacío.

Pagos con Telegram Stars en bots: facturas, pre-checkout, reembolsos y suscripciones

Acepta pagos con Telegram Stars en tu bot: sendInvoice con XTR, pre_checkout_query, successful_payment, reembolsos y suscripciones, con código.

Servidor de pruebas de Telegram: cómo probar un bot en el entorno de pruebas

Usa el servidor de pruebas de Telegram: entra al entorno de pruebas, crea un bot de prueba, llama a la Bot API con /test/ y activa TEST en nuestro tester.

Widgets de Telegram para tu sitio web: iniciar sesión con Telegram, posts, comentarios y botón compartir

Integra Telegram en tu sitio: iniciar sesión con Telegram (OIDC), el Login Widget clásico con verificación del hash, posts embebidos y botón compartir.

API JavaScript de TelegramWidget: referencia, eventos, errores y límites

Referencia de la API JavaScript TelegramWidget: propiedades, request(), eventos, errores, variables CSS, widget_query, answerWidgetQuery y límites.

Ejemplos de widgets de Telegram: HTML completo y bot en Python

Ejemplos de widgets de Telegram listos para usar: tarjeta de pedido, contador con widget_query, encuesta compartida en vivo y vista previa en el navegador.

Widgets de Telegram: HTML interactivo dentro de los mensajes de tu bot

Widgets de Telegram (Bot API 10.4): qué son, cómo funcionan sendWidget, chat_data y public_data, dónde se usan hoy y en qué difieren de las Mini Apps.

Cómo probar una Mini App de Telegram: del navegador a Telegram real

Cómo probar una Mini App de Telegram: modo mock en el navegador, localhost con túnel HTTPS, entorno de prueba, DevTools y validación de initData.