Telegram Bot API

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

· 8 min de lectura

Los widgets de Telegram son pequeños bloques HTML interactivos que un bot envía dentro de un mensaje con el método sendWidget, disponible desde Bot API 10.4 (9 de noviembre de 2026). Un widget es un documento HTML de hasta 32 KB que la app ejecuta en el dispositivo, sin red, con el estilo del chat: una tarjeta de pedido, un contador, una encuesta en vivo o un código promocional que se copia con un toque.

Dónde funcionan hoy: en producción, un bot solo puede enviar widgets al chat privado con el usuario, y esos mensajes van con contenido protegido, así que no se pueden reenviar. Los widgets en grupos, en modo inline y en reenvíos por ahora solo funcionan en el servidor de pruebas.

Qué es un widget de Telegram

Código y estado: chat_data y public_data

Un widget es código fijo más estado variable. El HTML se define al enviarlo y no cambia nunca: ningún método lo reemplaza. Lo que cambia es el estado, y solo el bot lo escribe. El widget lo lee como TelegramWidget.chatData y TelegramWidget.publicData y se vuelve a dibujar con los eventos chatDataChanged y publicDataChanged.

AspectoEstado del chat (chat_data)Estado compartido (public_data)
Ligado aUn mensaje originalEl mensaje de un widget estático, o un widget compartido allí donde aparezca
Quién lo veSolo ese chat (uno para todos los miembros en un grupo)Cualquiera que vea el widget
En un reenvíoNuncaUna copia (widget estático) o el estado vivo (widget compartido)
TamañoHasta 1024 bytes de textoHasta 1024 bytes de texto
Se cambia coneditMessageWidgetDataeditMessageWidgetData o editSharedWidgetData
EjemplosUna partida en curso, el estado de un pedidoResultados de una encuesta, un precio

Ambos son texto (normalmente JSON) que el servidor no interpreta; un estado ausente vale null.

Dónde viven los widgets: producción y servidor de pruebas

LugarCómo llegaSolicitudes (con allow_queries)Producción
Chat privado con el botsendWidget, sendSharedWidgetAl tocar y en segundo planoSí
Grupo básico o supergruposendWidgetSolo al tocarSolo servidor de pruebas
Cualquier chat salvo canales, vía el botModo inline (InputWidgetMessageContent, InputSharedWidgetMessageContent)Solo al tocarSolo servidor de pruebas
Un reenvío, incluidos canalesLo reenvían los usuariosAl tocar, solo widgets compartidosSolo servidor de pruebas

Los bots no pueden publicar widgets en canales, y las apps sin soporte muestran el caption. Los mensajes con widget no se pueden copiar con copyMessage ni copyMessages, y en grupos el permiso can_send_other_messages también cubre los widgets.

Widgets de Telegram vs. Mini Apps

AspectoMini AppWidget
DóndeUn WebView que se abre desde un botón, el menú o un enlaceDentro de la burbuja, siempre visible en el chat
CódigoUna página web en tu servidorHasta 32 KB de HTML dentro del mensaje, fijo tras el envío
MotorEl WebView de la plataformaSandbox QuickJS, dibujado por la app
RedToda la webNinguna
Comunicación con el botTu backend, con initData firmadoTelegramWidget.request() → actualización widget_query
EntradaTodo, teclado incluidoToques y eventos de puntero, sin teclado

Donde las APIs coinciden, TelegramWidget reutiliza los nombres de Telegram.WebApp (themeParams, onEvent, openLink, HapticFeedback). Para algo más grande, abre tu Mini App con openTelegramLink y pruébala en el Mini App Tester.

Envía tu primer widget con sendWidget

  1. Crea un bot y copia su token (cómo crear un bot en Telegram, dónde obtener el token).
  2. Envía /start al bot para que pueda escribirte y toma tu chat id de getUpdates.
  3. Llama a sendWidget. El parámetro html es un string, así que envía la petición como JSON:
curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendWidget" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 123456789,
    "html": "<h3>Tu código promocional</h3><p>Toca el botón para copiarlo.</p><button onclick=\"TelegramWidget.copyText(this.textContent)\">PROMO10</button>",
    "caption": "Tu código promocional: PROMO10"
  }'

Lo mismo en Python con requests o en JavaScript con fetch:

import requests

API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours"
html = """<h3>Tu código promocional</h3>
<p>Toca el botón para copiarlo.</p>
<button onclick="TelegramWidget.copyText(this.textContent)">PROMO10</button>"""

r = requests.post(f"{API}/sendWidget", json={
    "chat_id": 123456789,
    "html": html,
    "caption": "Tu código promocional: PROMO10",
}, timeout=10)
print(r.json())  # result: el Message enviado con su campo "widget"
const API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours";
const html = `<h3>Tu código promocional</h3>
<p>Toca el botón para copiarlo.</p>
<button onclick="TelegramWidget.copyText(this.textContent)">PROMO10</button>`;

const r = await fetch(`${API}/sendWidget`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    chat_id: 123456789,
    html,
    caption: "Tu código promocional: PROMO10",
  }),
  signal: AbortSignal.timeout(10_000),
});
console.log(await r.json()); // result: el Message enviado con su campo "widget"

Sin nada de CSS, el widget ya parece un mensaje normal con un botón nativo; copyText funciona porque se llama en el handler de un toque. También puedes pegar el HTML en el formulario de sendWidget del Bot API Tester y enviarlo con tu propio token.

Otros parámetros: width y height (anclas de tamaño), chat_data y public_data (estado inicial), allow_queries, is_shared y los habituales reply_markup, reply_parameters y protect_content.

Cómo se comunica un widget con el bot

Una solicitud funciona como un botón callback dentro del widget:

  1. El bot envía el widget con allow_queries: true.
  2. Al tocar, el widget llama a TelegramWidget.request("like") con 1 a 64 bytes de datos.
  3. El bot recibe un widget_query con id, from, chat, message_id y data (desde un reenvío de widget compartido, shared_widget_query). Si usas allowed_updates, incluye ambos.
  4. El bot llama a answerWidgetQuery en menos de 15 segundos, opcionalmente con data de hasta 1024 bytes que recibe solo el widget que preguntó.
  5. Para cambiar lo que ven todos, el bot llama a editMessageWidgetData (o editSharedWidgetData), y el widget recibe chatDataChanged / publicDataChanged.

La respuesta nunca cambia el estado; sin respuesta, el widget recibe TIMEOUT. El código completo está en los ejemplos de widgets de Telegram.

Widgets estáticos y compartidos

Sin is_shared el widget es estático: todo vive en el mensaje y un reenvío recibe una copia congelada. Con is_shared, el primer envío crea un widget compartido, un objeto con identificador (widget.id) que pueden mostrar muchos mensajes. Se reenvía con sendSharedWidget y su estado se cambia para todos con editSharedWidgetData, máximo una vez por segundo. Un widget en pantalla recibe el nuevo estado solo si llama a TelegramWidget.watchPublicData(); la app consulta cada 30 segundos por defecto (de 5 a 3600 con cache_time).

Límites de los widgets de Telegram

QuéLímite
HTML32768 bytes; 4096 bytes tras zlib nivel 9
chat_data, public_data1024 bytes cada uno
Datos de solicitud / de respuesta1–64 bytes / hasta 1024 bytes
Tiempo para responder15 segundos
Solicitudes5 cada 5 segundos por usuario y bot
Tamaño de la burbujaDe 200 px al ancho máximo de la burbuja, de 50 a 600 px de alto; lo demás se recorta
Ediciones de un widget compartido1 por segundo
Memoria / nodos DOM8 MB / 2000 nodos

La tabla completa, con cuotas de CPU, temporizadores y almacenamiento, está en la referencia de la API TelegramWidget.

Consejos de diseño

No confundir con los widgets para sitios web

"Widget de Telegram" también designa los widgets para sitios web: Telegram Login Widget, inserción de publicaciones y botón de compartir, scripts para tu propia web. Los de Bot API 10.4 son HTML que un bot envía a un chat. Los widgets para sitios web los explicamos en la guía de widgets de Telegram para web. La documentación oficial está en core.telegram.org/bots/widgets.

Siguientes pasos

Preguntas frecuentes

¿Qué son los widgets de Telegram?

Son bloques interactivos pequeños que se dibujan dentro de un mensaje del bot, añadidos en Bot API 10.4 (9 de noviembre de 2026). Cada widget es un documento HTML autónomo con CSS y JavaScript inline que la app de Telegram ejecuta en el dispositivo, en un sandbox sin acceso a la red.

¿Los widgets de Telegram funcionan en grupos?

En producción todavía no. Por ahora un bot solo puede enviar widgets al chat privado con el usuario, y no se pueden reenviar. Los grupos, el modo inline y los reenvíos ya funcionan en el servidor de pruebas.

¿Cómo envío un widget desde mi bot?

Llama a sendWidget con chat_id y html (texto de 1 a 32768 bytes, máximo 4096 bytes tras comprimir con zlib nivel 9), y de forma opcional caption, chat_data, public_data y allow_queries. El método devuelve el Message enviado con su campo widget.

¿Un widget puede hacer peticiones HTTP?

No. fetch, XMLHttpRequest, WebSocket y cualquier otra API de red lanzan NetworkDisabledError. La única salida es TelegramWidget.request(), que envía de 1 a 64 bytes al bot como una actualización widget_query.

¿Qué diferencia hay entre un widget y una Mini App?

Una Mini App es una página web que tú alojas y que se abre en un WebView desde un botón o enlace, con acceso completo a la red. Un widget vive dentro de la burbuja del mensaje, pesa como máximo 32 KB de HTML fijado al enviarlo, no tiene red y solo habla con su bot mediante solicitudes.

¿Puedo cambiar el HTML de un widget ya enviado?

No. El código queda fijo; solo cambia el estado. Actualiza chat_data o public_data con editMessageWidgetData o editSharedWidgetData, o envía un widget nuevo si necesitas otro diseño. El caption sí se edita con editMessageCaption.

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 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.

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.