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.

Actualizado el 9 de octubre de 2026. 2 min de lectura

Incluido en los planes Profesional y Avanzado. Ver precios

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

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

8 pasos

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.

TypeScript

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

TypeScript

import { initUtiliaWidget } from '@utilia-os/widget';
 
initUtiliaWidget({
  baseURL: 'https://os.utilia.ai/api',
  apiKey: 'TU_CLAVE_DE_API',
  userId: 'user-123',
  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.

En esta página

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.

Actualizado el 9 de octubre de 2026. 2 min de lectura

Incluido en los planes Profesional y Avanzado. Ver precios

Cuándo llega cada aviso

Crear un ticket desde el widget

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

8 pasos

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.

TypeScript

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 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`

TypeScript

import { initUtiliaWidget } from '@utilia-os/widget';
 
initUtiliaWidget({
  baseURL: 'https://os.utilia.ai/api',
  apiKey: 'TU_CLAVE_DE_API',
  userId: 'user-123',
  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.

En esta página