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[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#sdk-settings "Direct link to heading")

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[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#dark-mode "Direct link to heading")

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í](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/live-chat-dark-mode).

### Diseños del widget[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#widget-designs "Direct link to heading")

Chatwoot admite dos diseños para el widget.

1. Estándar (por defecto)

   ![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCTnVUNVFVPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--7dd398f5d3b26d370bf720c23f3854b580159d09/standard-bubble-chatwoot-live-chatwoot.gif)

2. Burbuja expandida

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCTnFUNVFVPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--7fa275e9d66e87a35323a0788c3ad19abfb64c9c/expanded-bubble-chatwoot-live-chatwoot.gif)

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[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#enable-popout-window "Direct link to heading")

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[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#enable-popout-window "Direct link to heading")

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[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#programatically-open-the-popout-window "Direct link to heading")

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[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#toggle-the-widget-bubble-visibility "Direct link to heading")

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[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#set-the-user-in-the-widget "Direct link to heading")

```
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[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#identity-validation-using-hmac "Direct link to heading")

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](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/identity-validation). Ten en cuenta que implementar autenticación HMAC permitirá que el historial de chat persista entre sesiones.

### Establecer atributos personalizados[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#set-custom-attributes "Direct link to heading")

Para establecer información adicional sobre el cliente, puedes utilizar el campo de atributos personalizados del cliente. Lee más sobre atributos personalizados [aquí](https://app.chatwoot.com/hc/chatwoot-user-guide-cloud-version/es/funciones-explicadas/49676).

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[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#set-language-manually "Direct link to heading")

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

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

### Establecer etiquetas en la conversación[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#set-labels-on-the-conversation "Direct link to heading")

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)[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#refresh-the-session-use-this-while-you-logout-the-user-from-your-app "Direct link to heading")

```
window.$chatwoot.reset();
```

### Errores del widget[​](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/setup#widget-errors "Direct link to heading")

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