Teclados de bots de Telegram: teclado inline, botones callback y reply keyboard
Un teclado inline de Telegram es un conjunto de botones pegado a un mensaje del bot: pasas un objeto InlineKeyboardMarkup en el parámetro reply_markup de sendMessage, y al presionar un botón callback tu bot recibe una actualización callback_query que debes responder con answerCallbackQuery. Un reply keyboard (ReplyKeyboardMarkup), en cambio, reemplaza el teclado de letras del usuario por respuestas predefinidas. Esta guía cubre los dos tipos de botones de bots de Telegram, cada tipo de botón, cómo editar el mensaje después de un clic y un ejemplo completo y funcional en Python y JavaScript.
Teclado inline o reply keyboard
| Teclado inline | Reply keyboard | |
|---|---|---|
| Objeto | InlineKeyboardMarkup | ReplyKeyboardMarkup |
| Dónde aparece | Debajo de un mensaje concreto | En lugar del teclado del usuario |
| Qué hace un clic | Callback query, abre una URL, una Mini App, el modo inline, copia texto… | Envía el texto del botón como mensaje, o comparte un contacto, una ubicación, usuarios o un chat |
| Se puede editar después | Sí, con editMessageReplyMarkup | No, envía un teclado nuevo o quítalo |
| Canales | Sí | No |
Los dos van en el mismo parámetro reply_markup, junto con ReplyKeyboardRemove y ForceReply. Un mensaje lleva solo uno de estos cuatro objetos.
Enviar un teclado inline de Telegram
inline_keyboard es un arreglo de filas, y cada fila es un arreglo de botones:
curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendMessage" \
-H "Content-Type: application/json" \
-d '{
"chat_id": 123456789,
"text": "Elige una opción:",
"reply_markup": {
"inline_keyboard": [
[{"text": "Me gusta", "callback_data": "like"}, {"text": "Ayuda", "callback_data": "help"}],
[{"text": "Docs de Bot API", "url": "https://core.telegram.org/bots/api"}]
]
}
}'
Además de text, cada botón debe tener exactamente un campo que define su tipo:
| Campo | Qué hace el botón |
|---|---|
callback_data | Envía al bot un callback query con esta cadena, de 1–64 bytes |
url | Abre un enlace HTTP o tg:// |
web_app | Abre una Mini App; solo en chats privados entre el usuario y el bot |
login_url | Abre una URL HTTPS e inicia la sesión del usuario en tu sitio |
switch_inline_query, switch_inline_query_current_chat, switch_inline_query_chosen_chat | Pone el username del bot y una consulta en el campo de texto de otro chat, del chat actual o de un chat del tipo elegido |
copy_text | Copia {"text": "…"} (1–256 caracteres) al portapapeles |
pay | Botón de pago; solo en mensajes de factura y debe ser el primer botón de la primera fila |
callback_game | Abre un juego; debe ser el primer botón de la primera fila |
disabled | Un DisabledButton que no hace nada (Bot API 10.3) |
Dos campos opcionales cambian el aspecto del botón (Bot API 9.4, también disponibles en los botones de reply keyboard): style con "danger" (rojo), "success" (verde) o "primary" (azul), e icon_custom_emoji_id para mostrar un emoji personalizado antes del texto. Los emojis personalizados solo funcionan si el bot puede usarlos: compró usernames adicionales en Fragment, o su dueño tiene Telegram Premium y el mensaje se envía directamente a un chat privado, grupo o supergrupo.
Cómo diseñar callback_data
El límite de 64 se cuenta en bytes, no en caracteres, así que usa valores cortos y fáciles de procesar, como like, page:3 o del:8812, y guarda los datos reales en tu base de datos. La API también advierte que el mensaje podría no tener ningún botón con el data que recibes, así que trátalo como entrada no confiable del usuario: parsea, valida y comprueba que el usuario tenga permiso para la acción. Un valor demasiado largo se rechaza al enviar el teclado, normalmente con Bad Request: BUTTON_DATA_INVALID.
Responde cada clic con answerCallbackQuery
Un clic en un botón callback genera una actualización con el campo callback_query: id, from (el usuario), data y, en mensajes enviados por el bot, message con el mensaje original. Después del clic, los clientes de Telegram muestran un indicador de progreso hasta que el bot llama a answerCallbackQuery, así que llámalo siempre, aunque no pases nada más que el id.
| Parámetro | Significado |
|---|---|
callback_query_id | Obligatorio, el id del callback query |
text | Texto de la notificación, 0–200 caracteres; si se omite, no se muestra nada |
show_alert | true muestra una alerta en lugar de una notificación en la parte superior del chat |
url | URL de un juego (para botones callback_game) o un enlace como t.me/your_bot?start=XXXX |
cache_time | Segundos que el cliente puede guardar el resultado en caché, 0 por defecto |
Responde rápido: un query viejo falla con Bad Request: query is too old and response timeout expired or query ID is invalid. Los detalles están en la referencia de answerCallbackQuery.
Editar el mensaje después de un clic
Actualizar el mensaje existente es más rápido y limpio que enviar uno nuevo, y Telegram lo recomienda para ajustes y paginación. Toma chat.id y message_id de callback_query.message y llama a:
editMessageTextpara cambiar el texto, opcionalmente con unreply_markupnuevo;editMessageReplyMarkuppara reemplazar solo el teclado; omitereply_markuppara quitarlo.
Si el texto y el teclado nuevos son idénticos a los actuales, la API responde Bad Request: message is not modified, así que compara antes de editar o ignora ese error en particular.
Ejemplo completo: menú inline con botones callback
Este bot responde a /start con un menú, cuenta los «me gusta» de cada mensaje, muestra una alerta con la ayuda y edita el mensaje en cada cambio. Usa long polling con getUpdates, así que corre en localhost sin webhook. Primero define BOT_TOKEN en las variables de entorno.
import os
import requests
TOKEN = os.environ["BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}"
likes = {} # (chat_id, message_id) -> contador
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 menu(count):
return {"inline_keyboard": [
[{"text": f"Me gusta ({count})", "callback_data": "like", "style": "success"},
{"text": "Reiniciar", "callback_data": "reset", "style": "danger"}],
[{"text": "Ayuda", "callback_data": "help"},
{"text": "Docs de Bot API", "url": "https://core.telegram.org/bots/api"}],
]}
def on_callback(cq):
msg, data = cq.get("message"), cq.get("data")
if not msg or data not in ("like", "reset", "help"):
call("answerCallbackQuery", callback_query_id=cq["id"], text="Botón desconocido")
return
if data == "help":
call("answerCallbackQuery", callback_query_id=cq["id"], show_alert=True,
text="Me gusta suma uno, Reiniciar vuelve a cero.")
return
key = (msg["chat"]["id"], msg["message_id"])
old = likes.get(key, 0)
new = old + 1 if data == "like" else 0
call("answerCallbackQuery", callback_query_id=cq["id"],
text="¡Gracias!" if data == "like" else "Contador reiniciado")
if new != old: # evita "message is not modified"
likes[key] = new
call("editMessageText", chat_id=key[0], message_id=key[1],
text=f"Me gusta: {new}", reply_markup=menu(new))
offset = 0
while True:
updates = call("getUpdates", offset=offset, timeout=30,
allowed_updates=["message", "callback_query"])
for update in updates:
offset = update["update_id"] + 1
if "callback_query" in update:
on_callback(update["callback_query"])
elif update.get("message", {}).get("text") == "/start":
chat_id = update["message"]["chat"]["id"]
call("sendMessage", chat_id=chat_id, text="Me gusta: 0", reply_markup=menu(0))const TOKEN = process.env.BOT_TOKEN;
const API = `https://api.telegram.org/bot${TOKEN}`;
const likes = new Map(); // "chatId:messageId" -> contador
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;
}
function menu(count) {
return { inline_keyboard: [
[{ text: `Me gusta (${count})`, callback_data: "like", style: "success" },
{ text: "Reiniciar", callback_data: "reset", style: "danger" }],
[{ text: "Ayuda", callback_data: "help" },
{ text: "Docs de Bot API", url: "https://core.telegram.org/bots/api" }],
] };
}
async function onCallback(cq) {
const msg = cq.message;
const data = cq.data;
if (!msg || !["like", "reset", "help"].includes(data)) {
await call("answerCallbackQuery", { callback_query_id: cq.id, text: "Botón desconocido" });
return;
}
if (data === "help") {
await call("answerCallbackQuery", { callback_query_id: cq.id, show_alert: true,
text: "Me gusta suma uno, Reiniciar vuelve a cero." });
return;
}
const key = `${msg.chat.id}:${msg.message_id}`;
const old = likes.get(key) ?? 0;
const next = data === "like" ? old + 1 : 0;
await call("answerCallbackQuery", { callback_query_id: cq.id,
text: data === "like" ? "¡Gracias!" : "Contador reiniciado" });
if (next !== old) { // evita "message is not modified"
likes.set(key, next);
await call("editMessageText", { chat_id: msg.chat.id, message_id: msg.message_id,
text: `Me gusta: ${next}`, reply_markup: menu(next) });
}
}
let offset = 0;
while (true) {
const updates = await call("getUpdates", { offset, timeout: 30,
allowed_updates: ["message", "callback_query"] });
for (const update of updates) {
offset = update.update_id + 1;
if (update.callback_query) {
await onCallback(update.callback_query);
} else if (update.message?.text === "/start") {
await call("sendMessage", { chat_id: update.message.chat.id, text: "Me gusta: 0",
reply_markup: menu(0) });
}
}
}Guarda la versión de JavaScript como bot.mjs (usa await de nivel superior) y ejecútala con Node.js 18+. El contador vive en memoria; un bot real lo guarda en una base de datos. Quita los campos style si prefieres los colores de botón por defecto.
Reply keyboard en Telegram
Un reply keyboard ofrece respuestas predefinidas. Un botón de texto simple, que también puede escribirse como una cadena, envía su texto al chat como si el usuario lo hubiera escrito, así que tu bot lo procesa como cualquier otro mensaje:
{
"keyboard": [
["Catálogo", "Carrito"],
[{"text": "Compartir mi teléfono", "request_contact": true},
{"text": "Enviar ubicación", "request_location": true}]
],
"resize_keyboard": true,
"one_time_keyboard": true,
"input_field_placeholder": "Elige una sección"
}
| Campo | Efecto |
|---|---|
resize_keyboard | Ajusta la altura a la cantidad de filas; por defecto el teclado mide lo mismo que el estándar |
one_time_keyboard | Oculta el teclado tras un clic; el usuario puede volver a abrirlo con el ícono del teclado |
is_persistent | Muestra siempre el teclado cuando el teclado normal está oculto |
input_field_placeholder | Texto de ejemplo en el campo de entrada, 1–64 caracteres |
selective | Muestra el teclado solo a los usuarios @mencionados o al autor del mensaje al que se responde |
Los botones especiales funcionan solo en chats privados: request_contact envía el número de teléfono del usuario como contacto, request_location su ubicación actual, request_poll le pide crear una encuesta y web_app abre una Mini App. request_users (KeyboardButtonRequestUsers) y request_chat (KeyboardButtonRequestChat) abren un selector y devuelven el resultado en los mensajes de servicio users_shared y chat_shared; ambos necesitan un request_id, un número de 32 bits con signo, único dentro del mensaje:
{"keyboard": [[
{"text": "Elegir un usuario", "request_users": {"request_id": 1, "user_is_bot": false, "max_quantity": 3}},
{"text": "Elegir mi grupo", "request_chat": {"request_id": 2, "chat_is_channel": false, "chat_is_created": true}}
]], "resize_keyboard": true}
ReplyKeyboardRemove y ForceReply
Un reply keyboard sigue visible hasta que el bot envía otro. Para quitarlo, envía un mensaje con {"remove_keyboard": true}. ForceReply, {"force_reply": true, "input_field_placeholder": "Tu ciudad"}, abre la interfaz de respuesta al mensaje del bot, como si el usuario hubiera tocado Responder. Es útil para pedir datos paso a paso en grupos, porque la respuesta le llega al bot aunque el modo de privacidad esté activado. Igual que los reply keyboards, ninguno de los dos objetos funciona en canales.
Pruébalo en Bot API Tester
- Abre sendMessage en Bot API Tester e ingresa tu token y tu chat id.
- Pega uno de los teclados JSON de arriba en
reply_markupy ejecuta. - Presiona un botón callback en Telegram, luego ejecuta
getUpdatesen el tester para ver la actualizacióncallback_queryy respóndela con answerCallbackQuery.
Problemas comunes con los botones de bots de Telegram
| Síntoma | Causa y solución |
|---|---|
| El botón se queda cargando tras el clic | Falta la llamada a answerCallbackQuery. Responde cada callback query. |
No llegan actualizaciones callback_query | allowed_updates no incluye callback_query, u otro proceso consume las actualizaciones (un webhook o una segunda instancia de polling). |
BUTTON_DATA_INVALID | callback_data está vacío o supera los 64 bytes. |
message is not modified | La edición no cambia ni el texto ni el teclado. |
query is too old… | La respuesta llegó tarde, por ejemplo cuando tras un reinicio se procesaron actualizaciones viejas. |
| El botón de contacto o ubicación no hace nada en un grupo | Esos botones solo están disponibles en chats privados. |
La lista completa de mensajes de error está en errores de la Telegram Bot API. El formato y las demás opciones de sendMessage se explican en cómo enviar mensajes con la Bot API, y los botones switch-to-inline se combinan con el modo inline.
Preguntas frecuentes
¿Qué diferencia hay entre un teclado inline y un reply keyboard en Telegram?
Un teclado inline (InlineKeyboardMarkup) va pegado a un mensaje concreto; presionar sus botones no envía nada al chat. Un reply keyboard (ReplyKeyboardMarkup) reemplaza el teclado de letras del usuario; un botón de texto simple envía su texto como un mensaje normal.
¿Qué tan largo puede ser callback_data?
De 1 a 64 bytes. Bytes, no caracteres: las letras con tilde, la ñ o los caracteres no latinos ocupan 2 o más bytes en UTF-8. Guarda claves cortas como item:42 y deja los datos reales en tu servidor.
¿Por qué un botón se queda cargando después de presionarlo?
El bot no llamó a answerCallbackQuery. Los clientes de Telegram muestran un indicador de progreso hasta que respondes, así que llámalo en cada callback query, aunque sea sin text.
¿Cómo cambio los botones después de que el usuario presiona uno?
Llama a editMessageReplyMarkup con el chat_id y el message_id de callback_query.message para reemplazar solo el teclado, o a editMessageText para cambiar el texto y el teclado a la vez.
¿Cómo quito un reply keyboard?
Envía un mensaje con reply_markup igual a {"remove_keyboard": true} (ReplyKeyboardRemove). Si solo quieres ocultarlo tras un clic y que siga disponible, usa one_time_keyboard.
¿Puedo agregar botones a los mensajes de un canal?
Teclados inline, sí. Los reply keyboards, ReplyKeyboardRemove y ForceReply no funcionan en canales.
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.
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.
Bot inline de Telegram: cómo activar el modo inline y responder consultas
Crea un bot inline de Telegram: activa el modo inline con @BotFather o setMySettings, procesa inline_query y responde con answerInlineQuery.
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.