Widgets de Telegram: HTML interactivo dentro de los mensajes de tu bot
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
- Un solo documento HTML.
<style>y<script>inline, imágenes solo como URLdata:o SVG inline. Máximo 32768 bytes en UTF-8 y 4096 bytes tras comprimir con zlib nivel 9. Basta un fragmento sin<html>ni<body>. - En sandbox. El JavaScript corre en QuickJS, un motor pequeño, no en un WebView. La app dibuja solo lo que permite el perfil de widgets, así que se ve igual en iOS, Android, macOS, Desktop y la web.
- Sin conexión.
fetch,XMLHttpRequest,WebSockety demás APIs de red lanzanNetworkDisabledError. No se cargan scripts, estilos, fuentes ni imágenes externas, y no viene ninguna biblioteca incluida. - Nativo. La paleta del chat está disponible como variables CSS
--tg-theme-*, y un<button>sin estilos se dibuja como el botón propio de la app. - Sin teclado. No hay inputs ni textareas; solo toques, punteros, arrastres horizontales y pulsaciones largas.
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.
| Aspecto | Estado del chat (chat_data) | Estado compartido (public_data) |
|---|---|---|
| Ligado a | Un mensaje original | El mensaje de un widget estático, o un widget compartido allí donde aparezca |
| Quién lo ve | Solo ese chat (uno para todos los miembros en un grupo) | Cualquiera que vea el widget |
| En un reenvío | Nunca | Una copia (widget estático) o el estado vivo (widget compartido) |
| Tamaño | Hasta 1024 bytes de texto | Hasta 1024 bytes de texto |
| Se cambia con | editMessageWidgetData | editMessageWidgetData o editSharedWidgetData |
| Ejemplos | Una partida en curso, el estado de un pedido | Resultados 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
| Lugar | Cómo llega | Solicitudes (con allow_queries) | Producción |
|---|---|---|---|
| Chat privado con el bot | sendWidget, sendSharedWidget | Al tocar y en segundo plano | Sí |
| Grupo básico o supergrupo | sendWidget | Solo al tocar | Solo servidor de pruebas |
| Cualquier chat salvo canales, vía el bot | Modo inline (InputWidgetMessageContent, InputSharedWidgetMessageContent) | Solo al tocar | Solo servidor de pruebas |
| Un reenvío, incluidos canales | Lo reenvían los usuarios | Al tocar, solo widgets compartidos | Solo 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
| Aspecto | Mini App | Widget |
|---|---|---|
| Dónde | Un WebView que se abre desde un botón, el menú o un enlace | Dentro de la burbuja, siempre visible en el chat |
| Código | Una página web en tu servidor | Hasta 32 KB de HTML dentro del mensaje, fijo tras el envío |
| Motor | El WebView de la plataforma | Sandbox QuickJS, dibujado por la app |
| Red | Toda la web | Ninguna |
| Comunicación con el bot | Tu backend, con initData firmado | TelegramWidget.request() → actualización widget_query |
| Entrada | Todo, teclado incluido | Toques 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
- Crea un bot y copia su token (cómo crear un bot en Telegram, dónde obtener el token).
- Envía
/startal bot para que pueda escribirte y toma tu chat id degetUpdates. - Llama a sendWidget. El parámetro
htmles 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:
- El bot envía el widget con
allow_queries: true. - Al tocar, el widget llama a
TelegramWidget.request("like")con 1 a 64 bytes de datos. - El bot recibe un
widget_queryconid,from,chat,message_idydata(desde un reenvío de widget compartido,shared_widget_query). Si usasallowed_updates, incluye ambos. - El bot llama a answerWidgetQuery en menos de 15 segundos, opcionalmente con
datade hasta 1024 bytes que recibe solo el widget que preguntó. - Para cambiar lo que ven todos, el bot llama a editMessageWidgetData (o
editSharedWidgetData), y el widget recibechatDataChanged/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 |
|---|---|
| HTML | 32768 bytes; 4096 bytes tras zlib nivel 9 |
chat_data, public_data | 1024 bytes cada uno |
| Datos de solicitud / de respuesta | 1–64 bytes / hasta 1024 bytes |
| Tiempo para responder | 15 segundos |
| Solicitudes | 5 cada 5 segundos por usuario y bot |
| Tamaño de la burbuja | De 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 compartido | 1 por segundo |
| Memoria / nodos DOM | 8 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
- Envía siempre un caption: lo muestran la lista de chats, las notificaciones y las apps sin soporte.
- Usa el tema. Construye los colores con las variables
--tg-theme-*y prueba los temas claro y oscuro;prefers-color-schemesigue el tema del chat, no el del sistema. - Mantenlo pequeño. Mide el tamaño comprimido con zlib nivel 9, igual que el servidor.
- Nada de secretos. Trata el código y el estado compartido como públicos; en un grupo todos los miembros ven el estado del chat.
- Diseña para el ancho con
%, flex o grid.vhno está soportado y nada hace scroll dentro de un widget. - Muestra cada resultado de una solicitud: "Enviando…", la respuesta y cada código de error.
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
- Ejemplos de widgets de Telegram: una tarjeta de pedido, un contador con solicitudes y una encuesta compartida en vivo, con el código del bot en Python.
- API JavaScript de TelegramWidget: propiedades, métodos, eventos, códigos de error, variables CSS y límites.
- Referencia de métodos de la Bot API.
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.
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 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.