Widget de soporte: visión general
Qué hace el widget de soporte, cómo separa los tickets de cada persona, qué necesitas antes de insertarlo y cuál de sus tres formas te conviene.
Actualizado el . 6 min de lectura
Incluido en los planes Profesional y Avanzado. Ver precios
El widget de soporte es un botón flotante que insertas en tu web o en tu aplicación para que tus usuarios abran tickets y sigan la respuesta sin salir de ella. Tu equipo los recibe y los contesta en UTILIA OS, en el aplicativo Tickets de soporte.
Se distribuye como el paquete npm @utilia-os/widget (versión 1.1.0) y funciona como un componente web propio, <utilia-support>, con sus estilos aislados del resto de tu página.
Qué ve tu usuario
- Un botón redondo en una esquina inferior de la pantalla, con un contador de mensajes sin leer.
- Al pulsarlo, la lista de sus tickets (los 20 con actividad más reciente).
- Un formulario para abrir un ticket nuevo: título (5 caracteres como mínimo), descripción (10 como mínimo), categoría, prioridad y hasta 5 archivos adjuntos.
- Un asistente con IA dentro del formulario que propone el título, la descripción, la categoría y la prioridad a partir de un texto libre o de una nota de voz.
- El detalle de cada ticket, con la conversación, donde puede seguir escribiendo mientras el ticket no esté cerrado.
Cómo se separan los tickets
El widget enseña a cada persona los tickets del identificador que le pasas, el userId. Como la clave del widget está a la vista en tu web, UTILIA OS necesita saber que ese userId es de verdad de quien está delante: tu servidor lo firma con el secreto del widget y el widget manda la firma con cada petición. Lo explica Verificar la identidad en el widget.
Sin la verificación, el userId no protege nada
Con la verificación en Desactivada o en Solo avisar, cualquiera con la clave y el userId de otra persona puede leer sus tickets y sus adjuntos y escribir en ellos. Las aplicaciones creadas antes de que existiera la verificación están en Desactivada.
Además de la verificación:
- Usa un identificador opaco. Un UUID aleatorio que guardes junto a cada usuario en tu base de datos. Nunca el correo, un número correlativo, el nombre ni el identificador que ya enseñas en direcciones o pantallas.
- No lo reutilices. Que no sirva también en otros sistemas ni en enlaces que compartes.
- Lleva lo delicado a tu servidor. Si un ticket puede contener datos de salud, bancarios o de terceros, no lo abras desde el navegador: crea y lista los tickets desde tu servidor con la API de tickets y la clave de una aplicación sin dominios autorizados, que nadie puede copiar.
Qué necesitas antes de empezar
Antes de insertar el widget
Integraciones
Crea la aplicación externa
Pulsa «Nueva aplicación», marca «Tickets y soporte» en «¿Para qué la usarás?» y pulsa «Crear la aplicación». La clave se muestra una sola vez: cópiala.Ficha de la aplicación
Ajusta los permisos
Añade los de archivos, IA y errores de la tabla siguiente, y quita «Leer usuarios», que el widget no usa.Si no: los adjuntos y el asistente fallan con 403.
Dominios autorizados
Declara tu dominio
Por ejemplo, https://www.tuempresa.example (se abre en una pestaña nueva). La API solo acepta llamadas de navegador desde dominios declarados.Si no: el navegador bloquea las llamadas del widget.
La aplicación se crea en Ajustes, Creadas por tu empresa, con el botón Nueva aplicación. Además, el plan de tu organización debe incluir Tickets de soporte (con la capacidad «Tickets propios»), Integraciones y, para los adjuntos, Gestor de archivos.
Una clave que va en una página web solo puede llevar los permisos de esta tabla, porque cualquiera puede copiarla. Por eso «Tickets y soporte» propone también «Leer usuarios» (crm:users:read), que sirve a una aplicación de servidor: quítalo antes de declarar tu dominio, o el panel no te dejará guardarlo.
| Scope | Para qué lo usa el widget |
|---|---|
crm:users:write | Dar de alta o actualizar a la persona que abre el ticket. |
support:tickets:read | Cargar la lista de tickets, el detalle y el contador de no leídos. |
support:tickets:write | Crear tickets y añadir mensajes. |
fm:files:write y fm:files:read | Subir adjuntos y abrirlos desde el detalle. |
support:tickets:ai | El asistente con IA y la nota de voz del formulario. |
analytics:errors:write | Enviar los errores del propio widget a tu registro de errores, con la dirección de la página donde ocurrieron. |
Si falta un scope, esa parte del widget falla con un error 403 INSUFFICIENT_SCOPE; el resto sigue funcionando. Tienes el detalle de cada uno en el catálogo de scopes.
Lo que el widget envía de la página
Con autoContext activado (lo está por defecto), cada ticket lleva la dirección completa de la página, con su cadena de consulta, y los datos del navegador. Los errores del widget también llevan esa dirección. Si tus direcciones llevan tokens o datos personales, desactívalo o límpialas antes de cargar el widget.
Si la clave se filtra, regenérala desde la ficha de la aplicación. Usa una aplicación dedicada solo al widget: los usuarios, los tickets y las facturas son de cada aplicación y no se comparten.
Quién firma las respuestas
En la ficha de la aplicación externa, pestaña «Widget» de su configuración, decides cómo ve tu usuario a quien le contesta. Con «Mostrar el nombre real del agente» activado, cada respuesta lleva el nombre de la persona de tu equipo que la escribe. Si lo desactivas, todas aparecen firmadas con el «Nombre personalizado del agente», o con «Equipo de Soporte» si lo dejas en blanco. Por defecto está desactivado.
Tres formas de instalarlo
Las tres cargan el mismo widget; cambia cuánto lo controlas desde tu código.
Cómo insertar el widget
Sin programar
Etiqueta de script
Desde tu código
Paquete npm
Declarativo
Componente web
Después puedes escuchar sus eventos y adaptar sus colores a tu marca.
Límite de peticiones
Todas las visitas de tu web comparten la clave de la aplicación, que admite 1.000 peticiones por hora. Cada carga de página con el widget hace dos (identificar al usuario y pedir el contador de no leídos), y abrir la lista o un ticket suma una más.
El asistente con IA gasta mucho más: mientras prepara una sugerencia, el widget pregunta por el resultado cada 800 milisegundos durante un minuto como mucho, así que una sola sugerencia puede consumir unas 75 peticiones. Las peticiones que llegan desde un dominio no autorizado también cuentan. Las cifras y qué hacer si te quedas corto están en los problemas frecuentes.
Siguiente paso
Ponlo en práctica
Lo encontrarás en Creadas por tu empresa. Para abrirlo, entra con tu cuenta de UTILIA OS.