SDK de chat en vivo

Eventos del SDK

El widget dispara un pequeño conjunto de CustomEvents en window. Escúchalos con window.addEventListener — los datos están en event.detail.

hellouone:ready

window.addEventListener('hellouone:ready', handler)

Se dispara una vez que el iframe terminó de cargar y window.$hellouOne está completamente disponible. Úsalo como condición previa para cualquier llamada de arranque — definir el usuario, abrir el panel, registrar atributos personalizados.

Detalle

event.detail es null. La señal en sí es el contenido.

Ejemplo

window.addEventListener('hellouone:ready', () => {
  window.$hellouOne.setUser('42', {
    name: 'Ada Lovelace',
    email: '[email protected]',
    identifier_hash: identifierHash
  });
});

hellouone:on-message

window.addEventListener('hellouone:on-message', handler)

Se dispara cada vez que se crea o actualiza un mensaje en la conversación activa — tanto los mensajes salientes del visitante como los mensajes entrantes del agente. El registro completo del mensaje se pasa en event.detail.

Forma del detalle

`id`	ID numérico del mensaje.
`conversation_id`	ID de la conversación a la que pertenece el mensaje.
`content`	El cuerpo del mensaje como string.
`content_type`	Normalmente `'text'`; los otros valores corresponden a tarjetas de entrada y formularios.
`content_attributes`	Datos estructurados adicionales — p. ej., `{ deleted: true }` cuando se elimina un mensaje.
`message_type`	`0` para mensajes salientes del agente, `1` para mensajes entrantes del visitante.
`sender_type`	`'Agent'` o `'User'`.
`created_at`	Marca de tiempo Unix (en segundos).
`attachments`	Arreglo de adjuntos; cada elemento incluye `data_url`, `file_type` y `extension`.

Ejemplo

window.addEventListener('hellouone:on-message', (event) => {
  const message = event.detail;
  if (message.sender_type === 'Agent') {
    analytics.track('support_message_received', {
      conversationId: message.conversation_id,
      length: message.content.length
    });
  }
});

También se dispara al actualizar

Este evento también se dispara cuando un mensaje existente se edita o se marca como eliminado. Si lo envías a tu herramienta de analítica, elimina duplicados por id.

hellouone:error

window.addEventListener('hellouone:error', handler)

Se dispara cuando una llamada del SDK falla en el servidor. El caso más común es un setUser rechazado cuando la validación de identidad es obligatoria y el hash no coincide.

Forma del detalle

event.detail contiene el error que devolvió el servidor. La forma exacta depende de la falla, pero espera al menos un string error. En las fallas de setUser aparece como 'SET_USER_ERROR'.

Ejemplo

window.addEventListener('hellouone:error', (event) => {
  console.warn('HellouOne error', event.detail);
});

Escuchar desde la página principal

Los eventos se disparan en el window de nivel superior, no en el iframe del widget. No necesitas montar nada con postMessage — basta con un addEventListener en la página donde insertaste el snippet.