Guía Completa del SDK de WhatChat para Envío de Información del Usuario #

El SDK del sitio web de WhatChat permite enviar información adicional de usuarios a la plataforma. Si has instalado nuestro código en tu sitio web, podrás acceder al objeto window.$whatchat. Para asegurarte de que el SDK se ha cargado completamente, escucha el evento whatchat:ready de la siguiente manera:

window.addEventListener("whatchat:ready", function () {
  // Utiliza window.$whatchat aquí
  // ...
});

Escuchar Mensajes del Widget #

Si deseas recibir mensajes del widget, puedes utilizar el siguiente evento:

window.addEventListener('whatchat:on-message', function(e) {
  console.log('whatchat:on-message', e.detail);
});

Configuración del SDK #

Para ocultar el icono del chat, utiliza la siguiente configuración:

Nota: Si usas esta opción, también debes activar el widget.

window.whatchatSettings = {
  hideMessageBubble: false,
  showUnreadMessagesDialog: false, // Desactivar el diálogo de mensajes no leídos
  position: "left", // Puede ser 'left' o 'right'
  locale: "es", // Lenguaje a establecer
  useBrowserLanguage: false, // Configurar el idioma del widget según el navegador del usuario
  type: "standard", // [standard, expanded_bubble]
  darkMode: "auto", // [light, auto]
  // baseDomain: "tudominio.com" // Configura si deseas rastrear usuarios en subdominios
};

Usar el Idioma del Navegador Automáticamente #

Para mostrar el widget de chat en el idioma del navegador del usuario, establece useBrowserLanguage en true en window.whatchatSettings.

Nota: Si useBrowserLanguage está establecido en true, se ignorará el valor de locale. Si el idioma del navegador no es compatible con WhatChat, se utilizará el idioma definido en locale. Si este también falta, el widget utilizará el idioma del panel de control de agentes.

Soporte para Modo Oscuro #

El widget de chat en vivo de WhatChat admite el modo oscuro a partir de la versión 2.4.0. Para habilitar el modo oscuro, sigue los pasos que se indican aquí.

Diseños del Widget #

WhatChat soporta dos diseños para el widget:

1. Estándar (predeterminado)
   

2. Burbuja Expandida
   

Si utilizas la burbuja expandida, puedes personalizar el texto mostrado en la burbuja configurando el parámetro launcherTitle en whatchatSettings de la siguiente manera:

window.whatchatSettings = {
  type: "expanded_bubble",
  launcherTitle: "Chatea con nosotros",
};

Habilitar Ventana Emergente #

Para habilitar la ventana emergente, añade la siguiente configuración a whatchatSettings. Esta opción está desactivada por defecto.

window.whatchatSettings = {
  // ... Otras Configuraciones
  showPopoutButton: true,
}

También puedes abrir la ventana de chat programáticamente utilizando el método popoutChatWindow().

Abrir Ventana Emergente Programáticamente #

Puedes abrir la ventana emergente programáticamente utilizando el método popoutChatWindow(). Para iniciar esto, llama al método como se muestra a continuación:

window.$whatchat.popoutChatWindow();

Alternar Visibilidad de la Burbuja #

Si deseas ocultar o mostrar la burbuja de widget de WhatChat, puedes hacerlo con toggleBubbleVisibility('show/hide').

Ejemplo #

window.$whatchat.toggleBubbleVisibility("show"); // Para mostrar la burbuja
window.$whatchat.toggleBubbleVisibility("hide"); // Para ocultar la burbuja

Activar Widget Programáticamente #

Si deseas abrir la ventana de chat al hacer clic en un enlace en el sitio web, sigue el método a continuación. En tu acción, llama al SDK de WhatChat como se describe:

window.$whatchat.toggle();

// Alternar widget pasando estado
window.$whatchat.toggle("open"); // Para abrir el widget
window.$whatchat.toggle("close"); // Para cerrar el widget

Establecer Usuario en el Widget #

window.$whatchat.setUser("<clave-de-identificación-del-usuario-único>", {
  email: "<correo-electrónico-del-usuario@tudominio.com>",
  name: "<nombre-del-usuario>",
  avatar_url: "<url-del-avatar-del-usuario>",
  phone_number: "<número-de-teléfono-del-usuario>",
});

El método setUser acepta un identificador, que puede ser user_id en tu base de datos o cualquier parámetro único que represente a un usuario. Puedes pasar email, name, avatar_url, phone_number como parámetros. El soporte para parámetros adicionales está en progreso.

Asegúrate de restablecer la sesión cuando el usuario cierre sesión en tu aplicación.

Validación de Identidad Usando HMAC #

Para prevenir la suplantación de identidad y mantener la conversación con tus clientes privada, se recomienda configurar la validación de identidad en WhatChat. La validación de identidad se habilita generando un HMAC (código de autenticación basado en hash) basado en el atributo identifier, utilizando SHA256. Junto con el identifier, también puedes pasar identifier_hash como se muestra a continuación para asegurarte de que el usuario es el correcto.

window.$whatchat.setUser(`<clave-de-identificación-del-usuario-único>`, {
  name: "", // Nombre del usuario
  avatar_url: "", // URL del avatar
  email: "", // Correo electrónico del usuario
  identifier_hash: "", // Hash de Identificador generado basado en el token hmac del widget web
  phone_number: "", // Número de teléfono del usuario
  description: "", // Descripción sobre el usuario
  country_code: "", // Código del país de dos letras
  city: "", // Ciudad del usuario
  company_name: "", // Nombre de la empresa
  social_profiles: {
    twitter: "", // Nombre de usuario de Twitter
    linkedin: "", // Nombre de usuario de LinkedIn
    facebook: "", // Nombre de usuario de Facebook
    github: "", // Nombre de usuario de Github
  },
});

Para generar el HMAC, consulta la documentación de validación de identidad. Ten en cuenta que implementar la autenticación HMAC permitirá que el historial de chat persista a través de sesiones.

Establecer Atributos Personalizados #

Para establecer información adicional sobre el cliente, puedes utilizar el campo de atributos personalizados. Lee más sobre atributos personalizados aquí.

Para establecer un atributo personalizado, llama a setCustomAttributes como sigue:

window.$whatchat.setCustomAttributes({
  accountId: 1,
  pricingPlan: "pago",
  // Aquí la clave que ya está definida en el atributo personalizado
  // El valor debe basarse en el tipo (Actualmente se admiten Número, Fecha, Cadena y Número)
});

Puedes ver esta información en el panel lateral de una conversación. Para eliminar un atributo personalizado, usa deleteCustomAttribute como sigue:

window.$whatchat.deleteCustomAttribute("clave-del-atributo");

Establecer Lenguaje Manualmente #

window.$whatchat.setLocale("es");

Para establecer el idioma manualmente, utiliza la función setLocale.

Establecer Etiquetas en la Conversación #

Ten en cuenta que las etiquetas se establecerán en una conversación si el usuario no ha comenzado una conversación. En ese caso, los siguientes ítems no tendrán ningún efecto:

window.$whatchat.setLabel("ticket-de-soporte");
window.$whatchat.removeLabel("ticket-de-soporte");

Refrescar la Sesión (usa esto cuando cierres sesión en tu aplicación) #

window.$whatchat.reset();

Errores del Widget #

Para ver cualquier error en el widget, asegúrate de escuchar el evento whatchat:error de la siguiente manera:

window.addEventListener("whatchat:error", function () {
  // ...
});

Nota: Esta función está disponible en la versión 2.3.0 y posteriores.

---

Con esta guía, estás listo para integrar y personalizar WhatChat en tu sitio web de manera efectiva. Si tienes más preguntas o necesitas más información, no dudes en consultar la documentación completa de WhatChat.