# Eventos y callbacks del widget

Los tres eventos que emite el widget de soporte y los dos callbacks con los que tu web reacciona a un ticket nuevo o a un error.

El widget de soporte avisa a tu página de lo que ocurre dentro de él de dos maneras: con **eventos** del navegador, que escuchas con `addEventListener` sobre el elemento `<utilia-support>`, y con **callbacks**, funciones que pasas en la configuración y que el widget llama en el momento oportuno. Sirven, por ejemplo, para registrar en tu analítica que alguien ha abierto un ticket o para mostrar un mensaje propio.

## Cuándo llega cada aviso

**Crear un ticket desde el widget**

Participantes: Tu página, Widget y UTILIA OS.

1. Tu página → Widget: open() o clic en el botón. El widget abre la lista de tickets de la persona.
2. Widget → Tu página (respuesta): Evento widget:open
3. Widget (por su cuenta): La persona rellena «Nuevo ticket» y pulsa «Enviar ticket».
4. Widget → UTILIA OS: `POST /api/external/v1/tickets`. Título, descripción, categoría, prioridad y adjuntos.
5. UTILIA OS → Widget (respuesta): Ticket creado. Con su id y su ticketKey.
6. Widget → Tu página (respuesta): onTicketCreated. Primero el callback, con el id y la ticketKey.
7. Widget → Tu página (respuesta): Evento ticket:created. Después el evento, con lo mismo en detail. El widget vuelve a la lista.
8. Tu página → Widget: close() o botón de cerrar. El widget emite widget:close y queda solo el botón flotante.

## Eventos

| Evento | Cuándo se emite | `detail` |
| - | - | - |
| `widget:open` | Al abrir el widget, con el botón flotante o con `open()`. | Ninguno |
| `widget:close` | Al cerrarlo, con su botón de cerrar o con `close()`. | Ninguno |
| `ticket:created` | Cuando la API confirma que el ticket se ha creado. | `{ id, ticketKey }` |

Los eventos no se propagan hacia arriba en el documento: escúchalos en el propio elemento, no en `document` ni en `window`.

```ts
const widget = document.querySelector('utilia-support');

widget?.addEventListener('widget:open', () => {
  console.log('Soporte abierto');
});

widget?.addEventListener('ticket:created', (event) => {
  const { id, ticketKey } = (event as CustomEvent<{ id: string; ticketKey: string }>).detail;
  console.log(`Ticket ${ticketKey} creado (${id})`);
});
```

Con la etiqueta de script, el elemento se crea cuando la página termina de cargarse. Si vas a escucharlo desde otro script, hazlo después del evento `DOMContentLoaded`.

Abrir el formulario de ticket nuevo o el detalle de un ticket no emite ningún evento.

## Callbacks

Solo están disponibles cuando configuras el widget desde tu código, con el [paquete npm](https://os.utilia.ai/docs/developers/widget/npm-react) o con el método `init` del elemento.

| Callback | Cuándo se llama | Qué recibe |
| - | - | - |
| `onTicketCreated` | Justo antes de emitir `ticket:created`. | `{ id: string; ticketKey: string }` |
| `onError` | Cuando falla una operación del widget. | Un objeto `Error` |

`onError` se llama si falla la identificación del usuario, la carga del contador de no leídos, de la lista o del detalle de un ticket, o la creación de un ticket. En este último caso, el formulario también muestra el mensaje de error a la persona.

```ts
import { initUtiliaWidget } from '@utilia-os/widget';

initUtiliaWidget({
  baseURL: 'https://os.utilia.ai/api',
  apiKey: 'TU_CLAVE_DE_API',
  userId: '9b2f6c1e-4d7a-4f0e-8a51-3c6d2e7f1a90',
  onTicketCreated: ({ ticketKey }) => {
    miAnalitica.track('ticket_creado', { ticketKey });
  },
  onError: (error) => {
    miRegistroDeErrores.capture(error);
  },
});
```

`ticketKey` es la clave legible del ticket, la misma que ve tu equipo en UTILIA OS. Puedes enseñársela a la persona para que la cite si escribe por otra vía.

## Siguiente paso

Si un error se repite, busca su causa en los [problemas frecuentes](https://os.utilia.ai/docs/developers/widget/troubleshooting).