Integración y configuración

Snippet básico

<script>
  window.WhaticketWidgetConfig = {
    token: "TOKEN_DE_LA_CONEXION", // token de una conexión Web Chat del CRM
    user: {
      externalId: "ID_DEL_USUARIO",  // requerido
      username: "NOMBRE_DE_USUARIO", // requerido
      email: "usuario@ejemplo.com",  // opcional
      phone: "5491100000000",        // opcional
      fullName: "Nombre Apellido",   // opcional
      lang: "es",                    // opcional
    },
  };
</script>
<script src="https://TU-CRM.com/widget-loader.js" async></script>

La configuración debe definirse antes de cargar el script: se lee una sola vez al evaluarse. Sin token el widget registra [WhaticketWidget] Falta window.WhaticketWidgetConfig.token y aborta.

Identidad del visitante

El modo lo define la conexión en el CRM (campo requiresAuth de la configuración devuelta por GET /widget/config; si el backend no lo informa, vale true):

requiresAuth	Identidad
false	Visitante anónimo user-<uuid>, generado y guardado en localStorage (permite recuperar el ticket abierto). externalId y username toman ese valor
true	La declara el sitio: config.user (o campos planos en la config) con externalId y username; si faltan, el widget no se renderiza hasta llamar init()

config.user también acepta los campos directamente en WhaticketWidgetConfig (config.user || config).

API pública

window.WhaticketWidget siempre existe, aunque no se haya pasado user:

Método	Descripción
init(userConfig)	Monta el widget con { externalId, username, email, phone, fullName, lang }. Sin externalId o username registra un error y no monta
destroy()	Desmonta (logout): avisa la salida, desconecta el socket y retira el DOM
open()	Abre el panel. No hace nada si el widget no está montado
close()	Cierra el panel

// Tras el login en el sitio
window.WhaticketWidget.init({ externalId, username, email, phone, fullName, lang });

// Al cerrar sesión
window.WhaticketWidget.destroy();

• init() con el mismo externalId ya montado es un no-op.
• init() con otro externalId desmonta la sesión anterior y monta de cero.

Opciones de configuración

Todas son opcionales salvo token. Los valores por defecto salen de SETTINGS y THEME en widget-loader.js.

Contenido y comportamiento

Opción	Por defecto	Descripción
token	obligatorio	Token de la conexión Web Chat
user	ninguno	Identidad (ver arriba)
lang	idioma del navegador	Idioma enviado al backend. Prioridad: user.lang / init(), luego config.lang, luego navigator.language (solo el subtag primario, es-AR pasa a es)
title	"Soporte"	Título del encabezado del panel
subtitle	""	Subtítulo
initialMessages	[]	Arreglo de textos que se muestran localmente cuando la conversación arranca vacía (no se persisten)
isAudioEnabled	ver notificationSound	Activa o silencia el sonido de notificación; si está definido, manda sobre notificationSound
notificationSound	true	Compatibilidad con embeds viejos; solo se usa si no hay isAudioEnabled

Botón flotante

Opción	Por defecto	Descripción
toggleButtonEnabled	true	Con false no se crea botón; el sitio usa open() y close()
toggleButtonBgColor	color primario	Fondo del botón
buttonSize	60	Diámetro en px
buttonIconSize	46,7 % de buttonSize (redondeado)	Tamaño del ícono en px
buttonOffset	20	Separación del borde (px)
buttonOffsetX	buttonOffset	Separación lateral; gana sobre buttonOffset en ese eje
buttonOffsetY	buttonOffset	Separación inferior; gana sobre buttonOffset en ese eje
buttonIcon	"💬"	Emoji, texto o markup SVG/HTML propio
position	"right"	"left" o "right"
draggable	false	true permite arrastrar con mouse o touch; la posición se guarda en localStorage
fullscreen	"never"	"never", "mobile" o "always"
fullscreenBreakpoint	768	Ancho en px; con fullscreen: "mobile" el panel ocupa toda la pantalla si window.innerWidth es menor o igual

Tema (theme)

Clave	Por defecto	Uso
primary	#25d366	Botón, encabezado, enlaces y acentos (si falta, se usa toggleButtonBgColor)
badgeColor	#ff3b30	Badge de no leídos
errorColor	#e53935	Grabación y errores
onlineDotColor	#b9f6ca	Punto de estado del encabezado
outBubbleColor	#d9fdd3	Burbuja de mensajes propios
inBubbleColor	#ffffff	Burbuja de mensajes entrantes
inBubbleBorderColor	#e6e6e6	Borde de burbuja entrante

Funciones del panel

• Panel flotante de 370 x 500 px (con tope calc(100vw - 40px) de ancho y calc(100vh - 120px) de alto) o pantalla completa según fullscreen.
• Responder (citar) un mensaje y saltar al original al tocar la cita.
• Adjuntar documentos (.pdf, .doc, .docx, .xls, .xlsx, máx. 10 MB), imágenes (jpeg, png, gif, máx. 5 MB), captura de pantalla, grabación de audio (1 a 120 s) o subir un archivo de audio.
• Indicador de estado de mensajes propios: ✓ (enviado) y ✓✓ (entregado o leído).
• Badge de no leídos, sonido y notificación del navegador (el permiso se solicita al primer clic en el botón) cuando llega una respuesta de agente y el widget no está visible.