Bot inline de Telegram: cómo activar el modo inline y responder consultas
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:
- 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. - El bot recibe una actualización
inline_query. - El bot llama a
answerInlineQuerycon una lista de resultados: artículos, fotos, GIFs, videos, stickers, ubicaciones y más. - 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. - Opcionalmente, el bot recibe una actualización
chosen_inline_resultque 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
- Envía
/setinlinea @BotFather y elige tu bot. - 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…
- Opcional:
/setinlinegeopide la ubicación del usuario con cada consulta;/setinlinefeedbackactiva las actualizacioneschosen_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:
supports_inline_queries:trueactiva el modo inline yfalselo desactiva.inline_query_placeholder: el texto del placeholder; una cadena vacía restaura el predeterminado.needs_inline_query_location: pide la ubicación del usuario con cada consulta inline.inline_feedback_share_denominator: recibir 1 de cada N resultados elegidos; debe ser 1, 10, 100 o 1000, y0detiene las actualizacioneschosen_inline_result.
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:
| Campo | Significado |
|---|---|
id | ID único de la consulta; pásalo a answerInlineQuery como inline_query_id |
from | El usuario que escribió la consulta |
query | Texto de la consulta, hasta 256 caracteres; puede venir vacío, y entonces conviene devolver resultados por defecto o populares |
offset | Desplazamiento de los resultados que hay que devolver; lo controla tu bot mediante next_offset |
chat_type | Opcional: sender (chat privado con quien envía la consulta), private, group, supergroup o channel; en chats secretos normalmente se desconoce |
location | Opcional; 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ámetro | Descripción |
|---|---|
inline_query_id | Obligatorio. El id de la consulta |
results | Obligatorio. Arreglo de objetos InlineQueryResult (≤ 50) |
cache_time | Tiempo máximo, en segundos, que el resultado puede quedar en caché en el servidor; 300 por defecto |
is_personal | true guarda la caché solo para este usuario; por defecto, cualquier usuario que envíe la misma consulta puede recibirlos |
next_offset | Offset que el cliente enviará con la siguiente consulta del mismo texto; cadena vacía si no hay más resultados; hasta 64 bytes |
button | InlineQueryResultsButton 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:
- article:
titleeinput_message_contentson obligatorios; opcionalesdescription,url,thumbnail_urlyreply_markup. El contenido suele ser unInputTextMessageContentconmessage_text(1–4096 caracteres) yparse_modeopcional. - photo:
photo_url(JPEG, hasta 5 MB) ythumbnail_urlson obligatorios; opcionalescaption(0–1024 caracteres),titleydescription.
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, "&").replace(/</g, "<").replace(/>/g, ">");
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 resultadosconst 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:
start_parameter: abre el chat privado con el bot y envía/start <parameter>; de 1 a 64 caracteres, soloA-Z,a-z,0-9,_y-.web_app: abre una Mini App, que puede volver al modo inline conswitchInlineQuery.
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íntoma | Causa probable y solución |
|---|---|
No pasa nada al escribir @tu_bot | El modo inline no está activado: usa /setinline o setMySettings. |
No llegan actualizaciones inline_query | Antes se configuró allowed_updates sin inline_query (la lista se recuerda) o hay un webhook activo y getUpdates devuelve 409 Conflict. |
| Siguen apareciendo resultados viejos | Caché 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 invalid | La respuesta llegó tarde o con un ID incorrecto. Responde de inmediato y haz el trabajo pesado en segundo plano. |
No llega chosen_inline_result | El feedback inline está desactivado: /setinlinefeedback o inline_feedback_share_denominator. |
| Los resultados con foto no aparecen | photo_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.
Guías relacionadas
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.