API JavaScript de TelegramWidget: referencia, eventos, errores y límites
La API de widgets de Telegram es el objeto window.TelegramWidget que la app entrega a cada widget de Bot API 10.4, más el lado del bot: las actualizaciones widget_query y el método answerWidgetQuery. Esta referencia resume propiedades, métodos, eventos, códigos de error, variables CSS, gestos y límites según la documentación oficial de widgets.
Disponibilidad: en producción, los widgets por ahora solo funcionan en el chat privado con el bot y no se pueden reenviar (van con contenido protegido). Los grupos, el modo inline y los reenvíos solo funcionan en el servidor de pruebas, así que propiedades comoisForwardochatType: "group"importan primero ahí.
¿Recién empiezas? Lee qué son los widgets de Telegram y los ejemplos de widgets.
Cómo aparece el objeto TelegramWidget
No hace falta ninguna etiqueta script: dentro de Telegram, window.TelegramWidget existe antes del primer script del widget; en un navegador normal es undefined. Los métodos añadidos dentro de un perfil se detectan con typeof:
const W = window.TelegramWidget; // undefined en un navegador normal
if (W && typeof W.setResizeAnchor === 'function') W.setResizeAnchor('bottom');
function render() {
let state = null;
try { state = JSON.parse(W.chatData); } catch (e) {}
// dibuja a partir de state; null significa "aún sin estado"
}
if (W) W.onEvent('chatDataChanged', render);
render();
Propiedades de TelegramWidget
| Propiedad | Descripción |
|---|---|
profile | Perfil de widget que aplica la app: 1 en esta versión |
colorScheme | light o dark, el esquema del chat |
themeParams | Paleta de la burbuja en #rrggbb, con las claves de themeParams de Mini Apps |
isActive | El widget está visible |
isPreview | Resultado inline antes de enviarse: sin toques ni solicitudes |
isForward | Es una copia reenviada |
chatType | private, group, supergroup, channel, o null en reenvío o vista previa |
viewer | id, first_name, last_name, username, is_premium de quien mira; solo donde el widget puede enviar solicitudes, si no null |
publicData | Estado compartido (hasta 1024 bytes) o null. Solo lectura |
chatData | Estado del chat (hasta 1024 bytes) o null; siempre null en un reenvío. Solo lectura |
contentSafeAreaInset | top, right, bottom, left, cornerLeft, cornerRight: zona cubierta por la hora del mensaje |
wallet | Wallet de Telegram o null |
HapticFeedback | Vibración háptica, ver abajo |
Métodos de TelegramWidget
| Método | Qué hace |
|---|---|
request(data[, options]) | Envía 1–64 bytes al bot. Devuelve una Promise de { result } o se rechaza con WidgetRequestError. Solo en un handler de toque, o en segundo plano donde se permita. options: { wallet: true } |
watchPublicData() / unwatchPublicData() | Inicia / detiene la consulta en vivo del estado de un widget compartido mientras está en pantalla |
copyText(text) | Copia 1–256 caracteres al tocar; la app muestra un aviso con el texto |
openLink(url) | Abre una URL https: (≤ 256 caracteres, no t.me) tras confirmar el usuario |
openTelegramLink(url) | Abre un enlace https://t.me/… dentro de Telegram |
setResizeAnchor(edge) | top (por defecto) o bottom: qué borde de la burbuja se queda fijo al cambiar la altura |
ready() | Opcional: avisa que el primer estado ya está dibujado |
onEvent(type, handler) / offEvent(type, handler) | Añade / quita un handler (máximo 16 por tipo de evento) |
isProfileAtLeast(n) | Devuelve profile >= n |
HapticFeedback ofrece impactOccurred(style) (light, medium, heavy, rigid, soft), notificationOccurred(type) (error, success, warning) y selectionChanged(). No existe sendMessage, y el widget no conoce su widget_id.
Eventos
| Evento | Cuándo |
|---|---|
themeChanged | Cambió el tema del chat; colorScheme, themeParams y las variables CSS ya están actualizados |
activated / deactivated | El widget se volvió visible / se ocultó |
chatDataChanged | El bot cambió el estado del chat. Nunca en un reenvío |
publicDataChanged | El bot cambió el estado compartido; en un widget compartido, solo mientras lo observa |
contentSafeAreaChanged | Cambió la zona cubierta por la hora del mensaje |
Los handlers se llaman sin argumentos y con this igual a TelegramWidget: lee los valores nuevos del objeto.
Códigos de WidgetRequestError
button.addEventListener('click', () => {
status.textContent = 'Enviando…';
TelegramWidget.request('vote:2').then(
(answer) => { status.textContent = answer.result ?? 'Listo'; },
(error) => { status.textContent = 'Error: ' + error.code; }, // error.name === 'WidgetRequestError'
);
});
| code | Significado |
|---|---|
NOT_ALLOWED | Sin allow_queries, reenvío de un widget estático, sin toque donde no hay segundo plano, o vista previa |
BUSY | Ya hay otra solicitud o llamada al wallet en curso |
RATE_LIMITED | Más de 5 solicitudes cada 5 segundos por usuario y bot |
TIMEOUT | El bot no respondió en 15 segundos |
FAILED | Lo demás: bot bloqueado o eliminado, mensaje borrado, fallo de red |
INVALID_ANSWER | La respuesta del bot excedió los límites |
Un data vacío o de más de 64 bytes lanza TypeError antes de enviar nada.
Lado del bot: widget_query y answerWidgetQuery
Una solicitud desde un mensaje original llega como widget_query; desde el reenvío de un widget compartido, como shared_widget_query. Si pasas allowed_updates a getUpdates o setWebhook, incluye ambos.
{
"update_id": 100000001,
"widget_query": {
"id": "8123456789012345678",
"from": {"id": 123456789, "is_bot": false, "first_name": "Alice"},
"chat": {"id": 123456789, "type": "private", "first_name": "Alice"},
"message_id": 4242,
"chat_instance": "901234567890123456",
"type": {"type": "data"},
"data": "refresh"
}
}
Responde a cada solicitud con answerWidgetQuery (widget_query_id y data opcional de hasta 1024 bytes) y cambia el estado aparte con editMessageWidgetData o editSharedWidgetData. Telegram fija from y widget_id, así que no se pueden falsificar, pero trata data como entrada no confiable.
curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/answerWidgetQuery" \
-H "Content-Type: application/json" \
-d '{"widget_query_id": "8123456789012345678", "data": "{\"n\":5,\"r\":3}"}'
Variables CSS
--tg-theme-bg-color,--tg-theme-text-color,--tg-theme-hint-color,--tg-theme-link-color: fondo, texto, texto secundario y enlaces.--tg-theme-button-color,--tg-theme-button-text-color,--tg-theme-secondary-bg-color,--tg-theme-accent-text-color,--tg-theme-destructive-text-color,--tg-theme-section-separator-color: botón, segunda superficie, acentos, acciones destructivas y separadores.--tg-color-scheme,--tg-text-font-size,--tg-text-line-height,--tg-text-padding,--tg-button-*: esquema, texto y estilo del botón de la app.--tg-content-safe-area-inset-*,--tg-content-safe-area-corner-left/-right: la banda donde se dibuja la hora (igual queenv(safe-area-inset-*)).
prefers-color-scheme, light-dark() y color-scheme siguen el tema del chat, no el del sistema.
Gestos y touch-action
Los toques son siempre del widget; los arrastres verticales siempre hacen scroll en el chat. Las pulsaciones largas y los arrastres horizontales se reclaman con CSS touch-action: none en un botón que se mantiene pulsado, un control de juego o un canvas; pan-y en un slider o carrusel horizontal; auto en todo lo demás. Usa eventos de puntero (los touch events no llegan) y deja libres los primeros 20 px del borde.
El perfil elimina inputs, selects y textareas, todas las APIs de red (NetworkDisabledError), recursos externos, vh, el scroll interno, alert, navigator.clipboard, iframe, video y WebGL. Lo eliminado no rompe el widget: simplemente se descarta.
Límites de los widgets de Telegram
| Límite | Valor | Si se supera |
|---|---|---|
| HTML | 32768 bytes; 4096 tras zlib nivel 9 | INPUT_MEDIA_WIDGET_TOO_LARGE |
chat_data, public_data | 1024 bytes cada uno | INPUT_MEDIA_WIDGET_DATA_TOO_LARGE |
| Datos de solicitud / respuesta | 1–64 bytes / 1024 bytes | TypeError / WIDGET_RESULT_TOO_LARGE |
| Tiempo de respuesta | 15 segundos | TIMEOUT; tarde: query is too old |
| Solicitudes | 5 cada 5 segundos | RATE_LIMITED |
| Ediciones de widget compartido | 1 por segundo; cache_time 5–3600 (30 por defecto) | Flood wait |
| CPU | 300 ms por segundo; 500 ms por tarea | Se frena; el widget se detiene |
| Memoria / nodos DOM | 8 MB / 2000 | El widget se detiene |
| Temporizadores | 64 activos | RangeError |
localStorage, sessionStorage | 4 KB por área y mensaje | QuotaExceededError |
Almacenamiento, enlaces, vibración y copyText
- Web Storage pertenece a este mensaje en este dispositivo: nunca se envía al bot ni se sincroniza. Envuelve
setItementry/catch. - Enlaces:
openLink,openTelegramLink,copyTextyrequestnecesitan un toque real: llámalos de forma síncrona en un handler declick, no trasawaitni en un temporizador. Un toque habilita una llamada. - Vibración solo con el widget visible, máximo 5 seguidas y 10 por segundo; en escritorio y web no suena nada.
- copyText copia 1–256 caracteres y siempre muestra un aviso con el texto copiado.
Pagos con el wallet de TON en breve
Dibuja un botón de pago solo si TelegramWidget.wallet no es null. Al tocar, el widget llama a request(data, { wallet: true }), el bot responde con una transacción nueva y el widget la pasa a wallet.sendTransaction() sin un segundo toque (dentro de 10 segundos):
TelegramWidget.request('pay:42', { wallet: true })
.then((a) => TelegramWidget.wallet.sendTransaction(JSON.parse(a.result), 'paid:42'))
.then((a) => show(a.result), (e) => showError(e.code));
Errores de la Bot API para widgets
INPUT_MEDIA_WIDGET_TOO_LARGE: HTML de más de 32768 bytes o 4096 bytes comprimido.INPUT_MEDIA_WIDGET_HTML_INVALID: UTF-8 inválido o un carácter NUL enhtml.INPUT_MEDIA_WIDGET_DATA_TOO_LARGE:chat_dataopublic_datade más de 1024 bytes.message is not modified: una edición que no cambia nada; tómala como éxito.
Prueba los métodos con tu token en el Bot API Tester y revisa los parámetros de sendWidget. Para conseguir el token, sigue cómo obtener el token de tu bot.
Preguntas frecuentes
¿Necesito incluir un script para usar TelegramWidget?
No. Dentro de Telegram, window.TelegramWidget ya existe antes de que corra el primer script del widget, con el estado, el tema y el contexto listos. Fuera de Telegram es undefined, así que compruébalo si abres el widget en un navegador.
¿Qué significa el error NOT_ALLOWED de WidgetRequestError?
El mensaje no puede enviar solicitudes: el widget se envió sin allow_queries, es el reenvío de un widget estático o una vista previa, o se llamó a request() fuera de un toque donde no se permiten solicitudes en segundo plano.
¿En cuánto tiempo debe responder el bot a un widget_query?
En 15 segundos, con answerWidgetQuery. Después la promesa del widget se rechaza con TIMEOUT y una respuesta tardía recibe query is too old. Responde siempre, incluso si algo falló.
¿Un widget puede cambiar su propio chatData o publicData?
No. Ambos son de solo lectura en el widget. Solo el bot escribe el estado, con sendWidget, editMessageWidgetData o editSharedWidgetData; el widget solo puede pedírselo con TelegramWidget.request().
¿Existe TelegramWidget.sendMessage?
No. Un widget nunca envía nada al chat en nombre del usuario. Solo puede mandar solicitudes a su bot, copiar texto, abrir enlaces y reproducir vibraciones.
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.
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.