Telegram Bot API

API JavaScript de TelegramWidget: referencia, eventos, errores y límites

· 9 min de lectura

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 como isForward o chatType: "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

PropiedadDescripción
profilePerfil de widget que aplica la app: 1 en esta versión
colorSchemelight o dark, el esquema del chat
themeParamsPaleta de la burbuja en #rrggbb, con las claves de themeParams de Mini Apps
isActiveEl widget está visible
isPreviewResultado inline antes de enviarse: sin toques ni solicitudes
isForwardEs una copia reenviada
chatTypeprivate, group, supergroup, channel, o null en reenvío o vista previa
viewerid, first_name, last_name, username, is_premium de quien mira; solo donde el widget puede enviar solicitudes, si no null
publicDataEstado compartido (hasta 1024 bytes) o null. Solo lectura
chatDataEstado del chat (hasta 1024 bytes) o null; siempre null en un reenvío. Solo lectura
contentSafeAreaInsettop, right, bottom, left, cornerLeft, cornerRight: zona cubierta por la hora del mensaje
walletWallet de Telegram o null
HapticFeedbackVibración háptica, ver abajo

Métodos de TelegramWidget

MétodoQué 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

EventoCuándo
themeChangedCambió el tema del chat; colorScheme, themeParams y las variables CSS ya están actualizados
activated / deactivatedEl widget se volvió visible / se ocultó
chatDataChangedEl bot cambió el estado del chat. Nunca en un reenvío
publicDataChangedEl bot cambió el estado compartido; en un widget compartido, solo mientras lo observa
contentSafeAreaChangedCambió 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'
  );
});
codeSignificado
NOT_ALLOWEDSin allow_queries, reenvío de un widget estático, sin toque donde no hay segundo plano, o vista previa
BUSYYa hay otra solicitud o llamada al wallet en curso
RATE_LIMITEDMás de 5 solicitudes cada 5 segundos por usuario y bot
TIMEOUTEl bot no respondió en 15 segundos
FAILEDLo demás: bot bloqueado o eliminado, mensaje borrado, fallo de red
INVALID_ANSWERLa 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

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ímiteValorSi se supera
HTML32768 bytes; 4096 tras zlib nivel 9INPUT_MEDIA_WIDGET_TOO_LARGE
chat_data, public_data1024 bytes cada unoINPUT_MEDIA_WIDGET_DATA_TOO_LARGE
Datos de solicitud / respuesta1–64 bytes / 1024 bytesTypeError / WIDGET_RESULT_TOO_LARGE
Tiempo de respuesta15 segundosTIMEOUT; tarde: query is too old
Solicitudes5 cada 5 segundosRATE_LIMITED
Ediciones de widget compartido1 por segundo; cache_time 5–3600 (30 por defecto)Flood wait
CPU300 ms por segundo; 500 ms por tareaSe frena; el widget se detiene
Memoria / nodos DOM8 MB / 2000El widget se detiene
Temporizadores64 activosRangeError
localStorage, sessionStorage4 KB por área y mensajeQuotaExceededError

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

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.

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.