SDK de chat en vivo

Métodos del SDK

Una vez que el widget se inicia, todos los métodos de tiempo de ejecución cuelgan del objeto window.$hellouOne. Ninguno está disponible antes de que se dispare el evento hellouone:ready — espéralo antes de llamar a cualquiera de los métodos de abajo.

Espera a ready

Envuelve cualquier llamada de arranque en un listener de hellouone:ready. El widget se ejecuta dentro de un iframe, así que el objeto global no existe en el instante en que se analiza tu snippet.

Apertura y visibilidad

toggle()

$hellouOne.toggle(state?: 'open' | 'close')

Abre o cierra el panel de chat. Sin argumento, invierte el estado actual. Pasa 'open' o 'close' para forzar un estado, sin importar dónde esté el panel ahora.

Ejemplo

// Abre el chat al hacer clic en tu propio botón
document.querySelector('#help-button').addEventListener('click', () => {
  window.$hellouOne.toggle('open');
});

toggleBubbleVisibility()

$hellouOne.toggleBubbleVisibility(visibility: 'show' | 'hide')

Oculta o vuelve a mostrar la burbuja del lanzador. El panel de chat sigue funcionando mientras la burbuja está oculta — útil cuando quieres abrirlo desde tu propia interfaz y no mostrar el lanzador flotante.

popoutChatWindow()

$hellouOne.popoutChatWindow()

Separa el chat en una pequeña ventana independiente del navegador (400×600). El token de conversación guardado en la cookie se conserva, así que el visitante llega al mismo hilo en el que ya estaba.

Identificar al usuario

setUser()

$hellouOne.setUser(identifier: string | number, user: object)

Asocia una identidad conocida a la conversación actual. El identifier es el ID estable del usuario en tu sistema; el objeto user lleva los campos visibles y (en modo seguro) la firma HMAC.

Campos del usuario

`name`	Nombre visible para los agentes.
`email`	Se usa para asociarlo con un contacto existente y para las respuestas salientes.
`avatar_url`	URL absoluta de una imagen de perfil.
`phone_number`	Teléfono en formato E.164, opcional.
`identifier_hash`	HMAC-SHA256 de `identifier`. Obligatorio cuando la bandeja de entrada está en modo de identidad obligatoria — consulta Validación de identidad.

Validación

identifier debe ser un string o un número.
El objeto user debe incluir al menos uno de name, email o avatar_url.
Llamar a setUser dos veces con exactamente el mismo contenido no hace nada — el SDK calcula un hash del contenido y omite la llamada de red.

Ejemplo

window.$hellouOne.setUser('42', {
  name: 'Ada Lovelace',
  email: '[email protected]',
  avatar_url: 'https://example.com/ada.png',
  identifier_hash: '<hash from your backend>'
});

reset()

$hellouOne.reset()

Borra la sesión del visitante: elimina la cookie de la conversación, descarta la identidad en caché y recarga el iframe. Llámalo al cerrar sesión. Si el panel está abierto, primero se cierra.

Atributos personalizados

Los atributos son metadatos arbitrarios de clave–valor. Los atributos de usuario se conservan en todas las conversaciones que ese visitante abra. Los atributos de conversación solo se aplican al hilo actual.

setCustomAttributes()

$hellouOne.setCustomAttributes(attributes: object)

Fusiona claves en el registro de contacto del visitante. El objeto debe contener al menos una clave — un objeto vacío lanza un error.

window.$hellouOne.setCustomAttributes({
  plan: 'pro',
  signupSource: 'partner'
});

deleteCustomAttribute()

$hellouOne.deleteCustomAttribute(name: string)

Elimina un solo atributo de usuario por su clave.

setConversationCustomAttributes()

$hellouOne.setConversationCustomAttributes(attributes: object)

Igual que setCustomAttributes, pero limitado a la conversación actual. Ideal para registrar la URL desde la que el visitante abrió el chat, el valor de su carrito, la variante A/B de la página, etc.

deleteConversationCustomAttribute()

$hellouOne.deleteConversationCustomAttribute(name: string)

Elimina un solo atributo de conversación por su clave.

Etiquetas

setLabel()

$hellouOne.setLabel(label: string)

Aplica una etiqueta a la conversación actual. Son las mismas etiquetas que usan los agentes para clasificar en el panel — útiles para enrutar o para informes (p. ej., etiquetar como pricing cada chat abierto desde /pricing).

removeLabel()

$hellouOne.removeLabel(label: string)

Quita de la conversación una etiqueta aplicada previamente.

Idioma y tema

setLocale()

$hellouOne.setLocale(locale: string)

Cambia el idioma de la interfaz del widget en tiempo de ejecución. Pasa un código ISO como 'en', 'es' o 'fr'. Si el valor está vacío, usa 'en' por defecto.

setColorScheme()

$hellouOne.setColorScheme(scheme: 'light' | 'dark' | 'auto')

Cambia entre el tema claro, el oscuro y el que define el sistema operativo. Cualquier valor distinto de esos tres vuelve a 'light'.