¿Cómo enviar información adicional del usuario a Chatwoot utilizando el SDK?

El SDK para sitios web de Chatwoot te permite enviar información adicional del usuario a Chatwoot.

Si has instalado nuestro código en tu sitio web, el SDK expondrá el objeto window.$chatwoot. Para asegurarte de que el SDK se haya cargado completamente, por favor asegúrate de escuchar el evento chatwoot:ready de la siguiente manera:

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

Si deseas escuchar los mensajes en el widget, puedes usar el siguiente evento.

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

Configuraciones del SDK​

Para ocultar la burbuja, puedes utilizar la configuración mencionada a continuación.

Nota: Si usas esto, también debes activar el widget.

window.chatwootSettings = {
  hideMessageBubble: false,
  showUnreadMessagesDialog: false, // Deshabilita el cuadro de mensajes no leídos
  position: "left", // Esto puede ser left o right
  locale: "en", // Idioma a establecer
  useBrowserLanguage: false, // Establece el idioma del widget desde el navegador del usuario
  type: "standard", // [standard, expanded_bubble]
  darkMode: "auto", // [light, auto]
  // baseDomain: "yourdomain.com" // configura si deseas rastrear usuarios entre subdominios
};

Usar el idioma del navegador automáticamente en tu widget de chat en vivo

Para mostrar el widget de chat en vivo en la configuración de idioma del navegador del usuario, establece useBrowserLanguage en true en window.chatwootSettings como se indicó arriba.

Nota: Si useBrowserLanguage está en true, se ignorará el locale especificado. Si el idioma del navegador no es compatible con chatwoot, se utilizará el valor indicado en locale. Si ese también falta, el widget utilizará el locale del panel de agente.

Modo Oscuro​

El widget de chat en vivo de Chatwoot es compatible con modo oscuro desde la versión v2.4.0. Para habilitar el modo oscuro, sigue los pasos mencionados aquí.

Diseños del widget​

Chatwoot admite dos diseños para el widget.

1. Estándar (por defecto)

   

2. Burbuja expandida

Si utilizas la burbuja expandida, puedes personalizar el texto usado en la burbuja estableciendo el parámetro launcherTitle en chatwootSettings como se muestra a continuación.

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

Habilitar ventana emergente​

Para habilitar la ventana emergente, agrega la siguiente configuración a chatwootSettings. Esta opción está deshabilitada por defecto.

window.chatwootSettings = {
  // ...Otras configuraciones
  showPopoutButton: true,
}

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

Mensajes personalizados​

Personaliza el mensaje de bienvenida y los mensajes de disponibilidad que se muestran en el encabezado del widget y los indicadores de estado del equipo.

window.chatwootSettings = {
  // ...Otras configuraciones

  welcomeTitle: "¿Necesitas ayuda?", // Encabezado personalizado del widget
  welcomeDescription: "Estamos aquí para apoyarte.", // Subtítulo del encabezado
  availableMessage: "¡Estamos en línea y listos para chatear!", // Cuando el equipo está disponible
  unavailableMessage: "Actualmente estamos fuera de línea." // Cuando el equipo no está disponible
};

Alternar funciones

Habilita o deshabilita funciones opcionales de la interfaz en el widget:

window.chatwootSettings = {
  // ...Otras configuraciones

  enableFileUpload: true, // Mostrar botón de adjuntar archivos
  enableEmojiPicker: true, // Habilitar selector de emojis en la caja de texto
  enableEndConversation: true // Permite que el usuario termine la conversación
};

Abrir programáticamente la ventana emergente​

Puedes abrir la ventana emergente programáticamente con el método popoutChatWindow().

Para iniciar esto, llama al método como se muestra a continuación.

window.$chatwoot.popoutChatWindow();

Alternar la visibilidad de la burbuja del widget​

Si deseas ocultar/mostrar la burbuja del widget de Chatwoot, puedes hacerlo con toggleBubbleVisibility('show/hide')

Ejemplo

window.$chatwoot.toggleBubbleVisibility("show"); // para mostrar la burbuja
window.$chatwoot.toggleBubbleVisibility("hide"); // para ocultar la burbuja

Activar el widget programáticamente

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

window.$chatwoot.toggle();

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

Establecer el usuario en el widget​

window.$chatwoot.setUser("<unique-identifier-key-of-the-user>", {
  email: "<email-address-of-the-user@your-domain.com>",
  name: "<name-of-the-user>",
  avatar_url: "<avatar-url-of-the-user>",
  phone_number: "<phone-number-of-the-user>",
});

setUser acepta un identificador que puede ser un 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 desarrollo.

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

Validación de identidad usando HMAC​

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

window.$chatwoot.setUser(`<unique-identifier-key-of-the-user>`, {
  name: "", // Nombre del usuario
  avatar_url: "", // URL del avatar
  email: "", // Correo electrónico del usuario
  identifier_hash: "", // Hash del identificador generado en base a webwidget hmac_token
  phone_number: "", // Número de teléfono del usuario
  description: "", // descripción sobre el usuario
  country_code: "", // Código de país de dos letras
  city: "", // Ciudad del usuario
  company_name: "", // Nombre de la compañía
  social_profiles: {
    twitter: "", // Nombre de usuario en Twitter
    linkedin: "", // Nombre de usuario en LinkedIn
    facebook: "", // Nombre de usuario en Facebook
    github: "", // Nombre de usuario en Github
  },
});

Para generar el HMAC, lee validación de identidad. Ten en cuenta que implementar autenticación HMAC permitirá que el historial de chat persista entre sesiones.

Establecer atributos personalizados​

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

Para establecer un atributo personalizado, usa setCustomAttributes como se muestra:

window.$chatwoot.setCustomAttributes({
  accountId: 1,
  pricingPlan: "paid",

  // Aquí la clave ya está definida en el atributo personalizado
  // El valor debe ser según el tipo (Actualmente soporta Number, Date, String y Number)
});

Puedes ver esta información en el panel lateral de una conversación.

Para eliminar un atributo personalizado, usa deleteCustomAttribute así:

window.$chatwoot.deleteCustomAttribute("attribute-key");

Establecer el idioma manualmente​

window.$chatwoot.setLocale("en");

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 iniciado una conversación. En ese caso, los siguientes elementos no tendrán ningún efecto:

window.$chatwoot.setLabel("support-ticket");

window.$chatwoot.removeLabel("support-ticket");

Refrescar la sesión (usa esto al cerrar sesión del usuario en tu app)​

window.$chatwoot.reset();

Errores del widget​

Para ver cualquier error en el widget, asegúrate de escuchar el evento chatwoot:event como se muestra:

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

Nota: Esta funcionalidad está disponible en la versión v2.3.0 y posteriores.

Personalizar el encabezado y descripción de bienvenida

Puedes cambiar:

• El título y la descripción de bienvenida

• Los mensajes que se muestran cuando tu equipo está en línea o fuera de línea

• Habilitar selectivamente funciones de la interfaz como carga de archivos, selector de emojis y botón para terminar la conversación

window.chatwootSettings = {
  welcomeTitle: '¿Necesitas ayuda?',
  welcomeDescription: 'Estamos aquí para apoyarte.',
  availableMessage: '¡Estamos en línea y listos para chatear!',
  unavailableMessage: 'Actualmente estamos fuera de línea.',

  enableFileUpload: true,
  enableEmojiPicker: true,
  enableEndConversation: true
 };