Widget HTML#

El bloque envía un widget: una pequeña tarjeta interactiva dentro del mensaje, como una encuesta, un cuestionario, una calculadora, un temporizador o una ruleta de premios. La persona toca la tarjeta, y el bot recibe la respuesta y sigue el escenario, como después de pulsar un botón.

El widget se muestra en los chats privados de Telegram y en el chat del sitio web. Los contactos de otros mensajeros van por la salida «Widget no mostrado»: conéctala con un mensaje normal.

Por dónde empezar#

En un bloque nuevo, el panel ofrece tres caminos:

• «Describir para la IA»: se abre el panel «Crear con IA». Describe la tarjeta con palabras, y la IA escribe su código y sus datos.
• «Escribir código»: se abre un editor HTML vacío.
• Una plantilla: una tarjeta lista que solo tienes que adaptar.

Plantillas: «Votación», «Valoración con estrellas», «Cuestionario», «Cuenta atrás», «Varias respuestas», «Una opción», «Deslizador», «Ruleta de premios», «Tarjeta de fidelidad», «Estado del pedido» y «Calculadora de precio». Al elegir una plantilla, bajo el campo aparece una pista: qué respuestas añadir y dónde cambiar los textos. También puedes elegir una plantilla más tarde con el botón «Plantillas» encima del editor. La plantilla elegida sustituye el código y los datos del widget.

Configuración#

El código, los datos y la vista previa están en las pestañas encima del editor:

• «Código HTML»: el marcado, los estilos y el script del widget. Bajo el campo ves cuánto ocupa y cuánto ocupa comprimido.
• «Datos»: los datos de este mensaje (chat_data), hasta 1024 bytes, normalmente JSON. El widget los lee como TelegramWidget.chatData. Conviene guardar aquí los textos y las opciones y dejar el código común.
• «Vista previa»: cómo se ve y funciona la tarjeta. El interruptor ☀/☾ cambia entre tema claro y oscuro, «Reiniciar» vuelve a iniciar el widget. Las solicitudes que el widget enviaría al bot aparecen bajo la vista previa.
• «En paralelo»: el código y la vista previa a la vez. La pestaña amplía el panel a pantalla completa y lo devuelve a su tamaño al pasar a otra pestaña.

Encima de la vista previa está el tamaño del widget:

• «Ancho»: «Auto» (el ancho del mensaje), 320, 400 o «Propio», de 200 a 600 puntos.
• «Alto»: «Auto» (según el contenido) o «Propio», de 50 a 600 puntos. Lo que no cabe se recorta: dentro del widget no hay desplazamiento.

Debajo del editor:

• «Pie»: texto bajo el widget, hasta 1024 caracteres.
• «Respuestas del widget»: las salidas del bloque, más abajo.
• «Avanzado»: «Guardar la respuesta en una variable del usuario» y «Enviar en silencio», consulta «Avanzado».

En el código y los datos funcionan las plantillas: {{ $name }} se sustituye antes del envío. La vista previa muestra el código tal cual, sin sustituciones.

Límites#

• El código, hasta 32 KB y hasta 4 KB comprimido. Si no cabe, puedes guardarlo, pero el widget no se envía: el contacto va por la salida «Widget no mostrado» y el motivo aparece en el «Registro de ejecución».
• No hay red: el widget no puede cargar scripts, estilos, fuentes ni imágenes por enlace, y no envía solicitudes. Las imágenes, solo como SVG incrustado o dirección data:.
• Los datos de un toque, hasta 52 bytes: unas 50 letras latinas; las letras con tilde y la ñ cuentan doble.
• Un mensaje con widget no se puede reenviar ni guardar.

Respuestas y salidas#

Un botón dentro del widget llama a TelegramWidget.request('si'), y el contacto sale por la salida «si», como si pulsara un botón con ese texto. El contacto no ve estos botones: solo enlazan los toques en el widget con el escenario.

• Respuestas del widget: añade una respuesta para cada valor que envía el widget.
• «Cualquier otra respuesta»: el widget envió un valor que no está entre las respuestas. Para guardarlo, activa «Guardar la respuesta en una variable del usuario».
• «Widget no mostrado»: el contacto no es de Telegram ni del chat del sitio web, el código supera el límite o Telegram rechazó el mensaje. Conecta la salida con un mensaje normal con el mismo sentido.
• «Continuar»: solo se ve en el esquema; el bot sigue adelante sin esperar un toque.

Los toques en widgets antiguos del historial del chat también llegan a este bloque.

Respuesta al widget y nuevo estado#

Después de la salida, el escenario puede responder al widget: define variables del contacto, por ejemplo con el bloque «Operación con variable» o «Intérprete de JavaScript»:

• widget_answer: lo que recibe el widget como respuesta a su solicitud. TelegramWidget.request() devuelve { result } con este valor.
• widget_chat_data: los nuevos datos del widget tocado. La tarjeta se vuelve a dibujar en el mismo mensaje.

Redibujar la tarjeta le corresponde al propio código del widget: con datos nuevos, la plataforma le envía el evento chatDataChanged. Pon el dibujo en una función y llámala al cargar y con el evento; si no, la tarjeta se queda como estaba. Las plantillas listas ya funcionan así.

function render() {
    const data = JSON.parse(TelegramWidget.chatData || '{}')
    // …
}
render()
TelegramWidget.onEvent('chatDataChanged', render)

Para actualizar el widget más tarde, por ejemplo cuando se paga un pedido, usa el bloque «Actualizar widget HTML».

Votación y ruleta de premios#

Dos claves en los datos del widget activan una mecánica lista, sin necesidad de escenario:

• "poll": ["Sí", "No"]: una votación, hasta 10 opciones. La plataforma cuenta los votos: un voto por contacto, y un voto repetido cambia la elección. El widget recibe el resultado: las opciones, el número de votos y la elección del propio contacto.
• "prizes": ["5% de descuento", …]: una ruleta de premios. El premio lo elige la plataforma: al azar y una vez por contacto.

La opción elegida o el premio obtenido se guarda en la variable del contacto widget_result antes de pasar por la salida, así que puedes insertarlo directamente en el siguiente mensaje: «Tu premio: {{ $widget_result }}».

Widgets del agente de IA#

El agente de IA también puede enviar widgets: activa la herramienta «Widgets HTML» en el bloque Agente de IA. Un toque en la tarjeta del agente le llega como mensaje del contacto.