Telegram Bot API

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

· 8 min de lectura

Telegram Bot API 10.5, publicada el 22 de noviembre de 2026, es la versión actual de la Bot API, con 194 métodos. La serie 10.x, que empezó con Bot API 10.0 el 8 de mayo de 2026, trajo el modo invitado, las fotos en vivo, los rich messages con borradores en streaming, los mensajes efímeros, las comunidades, las consultas de solicitudes de ingreso, los widgets HTML interactivos dentro de mensajes (10.4) y, en 10.5, el método setMySettings y el nuevo objeto BotFullInfo que devuelve getMe. A continuación verás las novedades de cada versión, con ejemplos JSON cortos y los cambios que pueden romper un bot existente.

Telegram Bot API 10 de un vistazo

VersiónFechaLo más importante
10.08 de mayo de 2026Modo invitado, fotos en vivo, multimedia en encuestas, eliminación de reacciones
10.111 de junio de 2026Rich messages y borradores rich, consultas de solicitudes de ingreso
10.214 de julio de 2026Mensajes efímeros, comunidades, actualización subscription, protección de origen de Mini Apps
10.324 de agosto de 2026EphemeralMessageParameters, borradores que se pueden detener, DisabledButton, botones en rich messages
10.49 de noviembre de 2026Widgets HTML, respuestas efímeras a callback queries en cualquier chat, citas de rich messages, tarjeta de billetera TON, temas para compartir chats
10.522 de noviembre de 2026setMySettings, BotFullInfo en getMe, callback_query_mode, enlaces de invitación al bot, bloques en citas expandibles

Bot API 10.0: modo invitado, fotos en vivo y encuestas

Modo invitado. Después de activar Guest Mode en la Mini App de @BotFather, los usuarios pueden mencionar a tu bot en chats de los que no es miembro. El bot recibe una actualización guest_message y puede enviar una respuesta con answerGuestQuery, pasando el guest_query_id del mensaje y un InlineQueryResult:

{
  "guest_query_id": "<message.guest_query_id>",
  "result": {
    "type": "article",
    "id": "1",
    "title": "Traducción",
    "input_message_content": {"message_text": "Bonjour tout le monde"}
  }
}

Un bot invitado no tiene acceso al historial del chat ni a la lista de miembros, y no verá los mensajes siguientes a menos que lo vuelvan a mencionar o le respondan.

Bot API 10.1: rich messages de Telegram y consultas de solicitudes de ingreso

Los rich messages sirven para contenido estructurado como reportes, documentación y respuestas de IA. sendRichMessage recibe un objeto rich_message con el contenido en html o markdown (10.2 agregó blocks explícitos y una lista media). Admite encabezados, listas y listas de tareas, tablas, citas, secciones desplegables, notas al pie, fórmulas LaTeX, mapas, collages, presentaciones y bloques multimedia. Límites: 32768 caracteres UTF-8, 500 bloques, 16 niveles de anidación, 50 archivos multimedia y 20 columnas de tabla.

curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendRichMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 123456789,
    "rich_message": {
      "markdown": "# Reporte semanal\n\n| Métrica | Valor |\n|:-------|------:|\n| Usuarios | **1204** |\n| Errores | 3 |\n\n- [x] Desplegar v2.1\n- [ ] Actualizar docs\n\n$$E = mc^2$$"
    }
  }'

sendRichMessageDraft transmite un rich message parcial a un chat privado mientras se genera. El borrador es una vista previa temporal de 30 segundos, así que termina con sendRichMessage. editMessageText ahora también acepta rich_message.

Consultas de solicitudes de ingreso. Cuando tu bot está configurado como bot guardián de un chat, la actualización chat_join_request trae un query_id. Decide al instante con answerChatJoinRequestQuery (approve, decline o queue para dejar la decisión a otros administradores), o muestra primero una Mini App con sendChatJoinRequestWebApp; la Mini App recibe chat_join_request_query_id en sus datos de inicio.

{"chat_join_request_query_id": "<chat_join_request.query_id>", "result": "approve"}

En 10.1 las encuestas también ganaron multimedia de tipo enlace.

Bot API 10.2: mensajes efímeros de Telegram, comunidades y seguridad de Mini Apps

Los mensajes efímeros son mensajes de grupo visibles solo para un usuario y el bot, lo que saca del historial compartido las pistas, los textos de bienvenida y los resultados personales. Los usuarios también pueden enviar comandos efímeros (BotCommand.is_ephemeral) que nadie más ve. Las reglas de entrega:

Los mensajes efímeros tienen sus propios métodos: editEphemeralMessageText, editEphemeralMessageMedia, editEphemeralMessageCaption, editEphemeralMessageReplyMarkup y deleteEphemeralMessage:

{"chat_id": -1001234567890, "receiver_user_id": 123456789, "ephemeral_message_id": 15}

Bot API 10.3: EphemeralMessageParameters, borradores que se pueden detener y DisabledButton

Cambio incompatible en los mensajes efímeros. Los parámetros de 10.2 receiver_user_id y callback_query_id se reemplazaron en 13 métodos de envío (sendMessage, sendPhoto, sendVideo, sendAnimation, sendAudio, sendDocument, sendLivePhoto, sendSticker, sendVideoNote, sendVoice, sendContact, sendLocation, sendVenue) por un solo objeto, ephemeral_message_parameters. sendRichMessage también lo acepta, y el nuevo replace_callback_query_message muestra el mensaje efímero en lugar del mensaje con el botón presionado:

{
  "chat_id": -1001234567890,
  "text": "Solo tú puedes ver esto.",
  "ephemeral_message_parameters": {
    "receiver_user_id": 123456789,
    "callback_query_id": "<callback_query.id>",
    "replace_callback_query_message": true
  }
}

Borradores que se pueden detener. Pasa can_stop a sendMessageDraft o sendRichMessageDraft para mostrar un botón Stop. Cuando el usuario lo presiona, tu bot recibe una actualización stopped_message_generation con chat y draft_id, y puedes cancelar el modelo. keep_on_stop deja visible el borrador parcial un tiempo; envíalo como mensaje normal si debe quedarse.

import time
import requests

API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours"
text, last = "", 0.0
for chunk in generate_reply():          # tu stream de tokens del LLM
    text += chunk
    if time.monotonic() - last > 0.5:   # no envíes un borrador por cada token
        requests.post(f"{API}/sendMessageDraft", json={"chat_id": 123456789,
                      "draft_id": 1, "text": text, "can_stop": True}, timeout=10)
        last = time.monotonic()
requests.post(f"{API}/sendMessage", json={"chat_id": 123456789, "text": text}, timeout=10)
const API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours";
const post = (method, body) => fetch(`${API}/${method}`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(body),
  signal: AbortSignal.timeout(10_000),
});

let text = "", last = 0;
for await (const chunk of generateReply()) {  // tu stream de tokens del LLM
  text += chunk;
  if (Date.now() - last > 500) {               // no envíes un borrador por cada token
    await post("sendMessageDraft", { chat_id: 123456789,
      draft_id: 1, text, can_stop: true });
    last = Date.now();
  }
}
await post("sendMessage", { chat_id: 123456789, text });

Bot API 10.4: widgets de Telegram, respuestas efímeras en cualquier chat y billetera TON

Widgets. Ahora los bots pueden enviar pequeños bloques HTML interactivos dentro de los mensajes. Un widget es un documento HTML (hasta 32768 bytes, 4096 bytes después de comprimir con zlib) que la app ejecuta en un sandbox sin acceso a la red, más un estado que solo el bot modifica: chat_data para un mensaje y public_data compartido en todos los lugares donde se muestra el widget. Métodos nuevos: sendWidget, sendSharedWidget, answerWidgetQuery, editMessageWidgetData y editSharedWidgetData; actualizaciones nuevas: widget_query y shared_widget_query; el modo inline recibe InputWidgetMessageContent e InputSharedWidgetMessageContent (por ahora solo en el servidor de prueba).

{
  "chat_id": 123456789,
  "html": "<h3>Pedido #1042</h3><p>2 × Margherita, 1 × Limonada</p><p><strong>Total: $23.50</strong></p>",
  "caption": "Pedido #1042: $23.50"
}

En producción, por ahora los widgets solo funcionan en chats privados y se envían con contenido protegido, así que no se pueden reenviar; los grupos, el modo inline y los reenvíos funcionan en el servidor de prueba. Los mensajes con widget no se pueden copiar con copyMessage / copyMessages, y el permiso can_send_other_messages ahora también cubre los widgets. Más detalles: qué son los widgets de Telegram.

Respuestas efímeras a callback queries en cualquier chat (excepto los chats de mensajes directos de canales). Pasa callback_query_id sin receiver_user_id en ephemeral_message_parameters y el mensaje se mostrará solo al usuario que presionó el botón. receiver_user_id y el parámetro chat_id de los métodos de envío ahora son opcionales. Igual tienes que llamar a answerCallbackQuery.

{
  "text": "Solo tú puedes ver esta respuesta.",
  "ephemeral_message_parameters": {"callback_query_id": "<callback_query.id>"}
}

Bot API 10.5: setMySettings, BotFullInfo y enlaces de invitación al bot

Ajustes del bot desde el código. El nuevo método setMySettings cambia ajustes que antes solo estaban en @BotFather. Todos los parámetros son opcionales, así que pasa solo los que quieres cambiar; el método devuelve True:

{
  "supports_inline_queries": true,
  "inline_query_placeholder": "Buscar recetas...",
  "can_join_groups": false,
  "has_topics_enabled": true,
  "callback_query_mode": "auto"
}

Envíalo a https://api.telegram.org/bot<token>/setMySettings o pruébalo con tu token en Bot API Tester y luego llama a getMe para revisar el resultado.

BotFullInfo (cambio incompatible). getMe ahora devuelve el nuevo objeto BotFullInfo en lugar de User, y los campos que antes solo devolvía getMe se quitaron de User. BotFullInfo además agrega active_usernames, inline_query_placeholder, needs_inline_query_location y has_topic_sidebar. El código que lee campos como can_join_groups, can_read_all_group_messages o supports_inline_queries del resultado de getMe sigue funcionando, porque esos campos están en BotFullInfo. Lo que se rompe es el código que los espera en otros objetos User y el código tipado que declara el resultado de getMe como User.

Cómo actualizar un bot a Bot API 10.5

  1. Actualiza tu librería (python-telegram-bot, aiogram, grammY, Telegraf y otras) a una versión cuyo changelog indique soporte para Bot API 10.5.
  2. Mueve receiver_user_id y callback_query_id al estilo 10.2 dentro de ephemeral_message_parameters.
  3. Si pasas una lista explícita en allowed_updates, agrega los tipos nuevos que procesas: guest_message, subscription, stopped_message_generation, widget_query, shared_widget_query.
  4. Relaja la validación de encuestas: ahora se permite una sola opción.
  5. En Mini Apps, asegúrate de que cada llamada a Telegram.WebApp se ejecute en el dominio registrado.
  6. Renombra StoryAreaPosition a AreaPosition si tu código se refiere al tipo por su nombre.
  7. Trata el resultado de getMe como BotFullInfo y deja de leer campos exclusivos de getMe, como can_join_groups, en otros objetos User.
  8. En los rich messages, arma las citas expandibles con blocks en lugar de text.
  9. Si cambias callback_query_mode a "auto" o "inline", haz que tu handler de callbacks acepte inline_message_id cuando falte message.
  10. Prueba los métodos nuevos con tu token en Bot API Tester: setMySettings, sendWidget, sendRichMessage, deleteEphemeralMessage y answerChatJoinRequestQuery.

Los mensajes efímeros y los normales comparten las mismas bases, así que enviar mensajes con la Bot API sirve como repaso, y los límites de la Telegram Bot API muestra los límites de los rich messages junto a los clásicos. El historial completo está en el changelog oficial de la Bot API.

Preguntas frecuentes

¿Cuál es la versión más reciente de la Telegram Bot API?

Bot API 10.5, publicada el 22 de noviembre de 2026, con 194 métodos. Es la sexta versión de la serie 10.x, que empezó con Bot API 10.0 el 8 de mayo de 2026. Agregó setMySettings, que permite al bot cambiar sus propios ajustes, y ahora getMe devuelve BotFullInfo. La versión anterior, 10.4 (9 de noviembre de 2026), trajo los widgets HTML en mensajes.

¿Qué son los rich messages en Telegram?

Los rich messages (Bot API 10.1) son mensajes estructurados que se envían con sendRichMessage: encabezados, listas, tablas, fórmulas LaTeX, bloques multimedia, mapas y, desde 10.3, botones. El contenido se pasa como HTML, Markdown o bloques en rich_message, hasta 32768 caracteres UTF-8.

¿Qué son los mensajes efímeros en los bots de Telegram?

Los mensajes efímeros (Bot API 10.2) son mensajes en un grupo o supergrupo que solo ven un usuario y el bot. Desde 10.3 se envían con ephemeral_message_parameters en sendMessage y otros métodos de envío; desde 10.4 el bot también puede responder de forma efímera a un callback query en cualquier chat, excepto los chats de mensajes directos de canales. La entrega no está garantizada, sobre todo si el usuario está desconectado.

¿Cómo hago streaming de respuestas de IA en un bot de Telegram?

En un chat privado, llama varias veces a sendMessageDraft o sendRichMessageDraft con el mismo draft_id y después envía el texto final con sendMessage o sendRichMessage, porque un borrador es solo una vista previa temporal de 30 segundos. Con can_stop el usuario ve un botón Stop y tu bot recibe stopped_message_generation.

¿Qué es setMySettings en Telegram Bot API 10.5?

setMySettings permite que un bot cambie sus propios ajustes sin @BotFather: modo inline, modo de privacidad, unirse a grupos, conexiones de negocio, consultas de invitado y de solicitudes de ingreso, temas en chats privados, comunicación entre bots y callback_query_mode. Pasa solo los campos que quieres cambiar; devuelve True. Los valores actuales se obtienen con getMe, que ahora devuelve BotFullInfo.

¿Qué es el modo invitado en Telegram Bot API 10.0?

El modo invitado (guest mode) permite que un bot responda cuando lo mencionan en un chat del que no es miembro. El bot recibe una actualización guest_message y responde una vez con answerGuestQuery, sin acceso al historial del chat. Se activa en la Mini App de @BotFather.

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.

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.

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.