# 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.

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](https://os.utilia.ai/docs/guides/support-tickets/overview).

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](https://os.utilia.ai/docs/developers/widget/identity-verification).

> **Atención: 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](https://os.utilia.ai/docs/developers/api/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**

1. **Crea la aplicación externa** (Integraciones): 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.
2. **Ajusta los permisos** (Ficha de la aplicación): 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.
3. **Declara tu dominio** (Dominios autorizados): Por ejemplo, <https://www.tuempresa.example>. La API solo acepta llamadas de navegador desde dominios declarados. Si no: el navegador bloquea las llamadas del widget.
4. [**Firma el userId**](https://os.utilia.ai/docs/developers/widget/identity-verification) (Tu servidor): Con el secreto del widget, para cada persona que inicia sesión.
5. [**Inserta el widget**](https://os.utilia.ai/docs/developers/widget/script-tag) (Tu web): Con una etiqueta de script, por npm o como componente web.

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](https://os.utilia.ai/docs/developers/api/scopes-catalog).

> **Nota: 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**

### Etiqueta de script (Sin programar)

Para webs sin proceso de compilación: pegas una etiqueta con atributos data- y el widget arranca solo. [Ver cómo](https://os.utilia.ai/docs/developers/widget/script-tag).

### Paquete npm (Desde tu código)

Para aplicaciones con React, Vue, Svelte o un empaquetador: lo abres desde tus botones y recibes los callbacks. [Ver cómo](https://os.utilia.ai/docs/developers/widget/npm-react).

### Componente web (Declarativo)

La etiqueta utilia-support en tu HTML, configurada con atributos. [Ver cómo](https://os.utilia.ai/docs/developers/widget/web-component).

Después puedes [escuchar sus eventos](https://os.utilia.ai/docs/developers/widget/events-and-callbacks) y [adaptar sus colores](https://os.utilia.ai/docs/developers/widget/css-variables) 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](https://os.utilia.ai/docs/developers/widget/troubleshooting).

## Siguiente paso

- [Insertar con una etiqueta de script](https://os.utilia.ai/docs/developers/widget/script-tag): La forma más rápida: sin compilar ni escribir JavaScript.
- [Tickets de soporte](https://os.utilia.ai/docs/guides/support-tickets/overview): Cómo contesta tu equipo los tickets que llegan del widget.