Telegram Bot API

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

· 9 min de lectura

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 inlineReply keyboard
ObjetoInlineKeyboardMarkupReplyKeyboardMarkup
Dónde apareceDebajo de un mensaje concretoEn lugar del teclado del usuario
Qué hace un clicCallback 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ésSí, con editMessageReplyMarkupNo, envía un teclado nuevo o quítalo
CanalesSí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:

CampoQué hace el botón
callback_dataEnvía al bot un callback query con esta cadena, de 1–64 bytes
urlAbre un enlace HTTP o tg://
web_appAbre una Mini App; solo en chats privados entre el usuario y el bot
login_urlAbre 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_chatPone 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_textCopia {"text": "…"} (1–256 caracteres) al portapapeles
payBotón de pago; solo en mensajes de factura y debe ser el primer botón de la primera fila
callback_gameAbre un juego; debe ser el primer botón de la primera fila
disabledUn 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ámetroSignificado
callback_query_idObligatorio, el id del callback query
textTexto de la notificación, 0–200 caracteres; si se omite, no se muestra nada
show_alerttrue muestra una alerta en lugar de una notificación en la parte superior del chat
urlURL de un juego (para botones callback_game) o un enlace como t.me/your_bot?start=XXXX
cache_timeSegundos 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:

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"
}
CampoEfecto
resize_keyboardAjusta la altura a la cantidad de filas; por defecto el teclado mide lo mismo que el estándar
one_time_keyboardOculta el teclado tras un clic; el usuario puede volver a abrirlo con el ícono del teclado
is_persistentMuestra siempre el teclado cuando el teclado normal está oculto
input_field_placeholderTexto de ejemplo en el campo de entrada, 1–64 caracteres
selectiveMuestra 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

  1. Abre sendMessage en Bot API Tester e ingresa tu token y tu chat id.
  2. Pega uno de los teclados JSON de arriba en reply_markup y ejecuta.
  3. Presiona un botón callback en Telegram, luego ejecuta getUpdates en el tester para ver la actualización callback_query y respóndela con answerCallbackQuery.

Problemas comunes con los botones de bots de Telegram

SíntomaCausa y solución
El botón se queda cargando tras el clicFalta la llamada a answerCallbackQuery. Responde cada callback query.
No llegan actualizaciones callback_queryallowed_updates no incluye callback_query, u otro proceso consume las actualizaciones (un webhook o una segunda instancia de polling).
BUTTON_DATA_INVALIDcallback_data está vacío o supera los 64 bytes.
message is not modifiedLa 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 grupoEsos 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.

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.