Widget de soporte: visión general
Qué hace el widget de soporte, qué necesitas antes de insertarlo en tu web y cuál de las tres formas de instalarlo te conviene.
Actualizado el . 4 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.
El widget identifica a cada persona con el identificador que le das (userId): solo ve sus propios tickets.
Qué necesitas antes de empezar
Antes de insertar el widget
Aplicaciones externas
Crea la aplicación externa
Pulsa «Crear app» y elige «Tickets y soporte» en «¿Para qué la usarás?». La clave de API se muestra una sola vez: cópiala.Ficha de la aplicación
Completa los scopes
«Tickets y soporte» concede los de usuarios y tickets; añade a mano los de archivos y el de IA de la tabla siguiente.Si no: los adjuntos y el asistente con IA fallan con 403.
Dominios autorizados
Declara tu dominio
Por ejemplo, https://www.tuempresa.com (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 › Integraciones › Aplicaciones externas, necesitas entrar con tu cuenta. 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.
| 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. |
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.
La clave de API queda a la vista
El widget lleva la clave en el código de tu página, así que cualquiera que la mire puede leerla. Usa una aplicación externa dedicada solo al widget, con los scopes de la tabla y ninguno más, y con tus dominios en «Dominios autorizados». Si la clave se filtra, regenérala desde la ficha de la aplicación.
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. Las cifras y qué hacer si te quedas corto están en los problemas frecuentes.
Siguiente paso
Elige la forma de instalarlo e insértalo en una página de prueba. Cuando abras el primer ticket, lo verás en UTILIA OS junto al resto: así se trabaja con ellos en Tickets de soporte. Si el widget no aparece o da errores, repasa los problemas frecuentes.
Ponlo en práctica
Lo encontrarás en Aplicaciones externas. Para abrirlo, entra con tu cuenta de UTILIA OS.