API JavaScript del Widget

Introducción

Cuando el script del widget se carga en tu página, expone el objeto global window.PlzWidget. Con el puedes abrir o cerrar el chat desde tus propios botones, enviar mensajes, identificar al usuario que inicio sesión en tu sitio y reaccionar a lo que ocurre en la conversación.

La API es compatible con versiones anteriores: open(), close() y toggle() funcionan igual que siempre. El resto de métodos son adicionales.

El script del widget se instala con defer, así que window.PlzWidget no existe hasta que el script se ejecuta. Para usar la API apenas este disponible, define window.PlzWidgetOnLoad antes del script del widget:

html

01<script>
02  window.PlzWidgetOnLoad = function (PlzWidget) {
03    PlzWidget.on('ready', function () {
04      console.log('Widget listo');
05    });
06  };
07</script>
08 
09<script id="id-widget-agent-plz" type="module" defer
10  src="https://storagelaplazbot.z13.web.core.windows.net/widget.js?Id={ID_AGENT}&zone={ZONE}&workspaceId={WORKSPACE_ID}">
11</script>

PlzWidgetOnLoad se ejecuta en cuanto window.PlzWidget existe.
El evento ready se dispara cuando la configuración del agente término de cargar. Si te suscribes a ready cuando el widget ya estaba listo, el callback se ejecuta de inmediato.
Los métodos sendMessage e identify se pueden llamar antes de ready: quedan en cola y se ejecutan al cargar la configuración.

Métodos

Método	Descripción
`open()`	Abre el widget
`close()`	Cierra el widget
`toggle()`	Abre o cierra el widget según su estado actual
`isOpen()`	Devuelve `true` si el widget esta abierto
`sendMessage(text)`	Abre el chat y envía `text` como si lo hubiera escrito el usuario
`identify(data)`	Registra los datos del usuario en el contacto (ver abajo)
`hideLauncher()`	Oculta el botón flotante del widget
`showLauncher()`	Vuelve a mostrar el botón flotante
`getUnreadCount()`	Devuelve la cantidad de mensajes sin leer
`on(evento, callback)`	Suscribe un callback a un evento. Devuelve una función para cancelar la suscripción

Abrir el chat desde tu propio botón

html

01<button onclick="PlzWidget.open()">Hablar con soporte</button>

Si prefieres usar solo tu botón, oculta el botón flotante del widget:

01PlzWidget.hideLauncher();

Enviar un mensaje

Útil para iniciar una conversación con contexto, por ejemplo desde la página de un producto:

01PlzWidget.sendMessage('Quiero información sobre el Plan Pro');

Si el agente tiene activo el formulario de registro (formWidget) y el usuario aun no lo completo, sendMessage abre el widget en el formulario y no envía el mensaje. Usa identify antes para omitir el formulario.

Identificar al usuario

Si el usuario ya inicio sesión en tu sitio, envía sus datos para que el contacto en el CRM quede con nombre, email y teléfono:

01PlzWidget.identify({
02  name: 'Maria',
03  lastname: 'Lopez',
04  email: 'maria@empresa.com',
05  phone: '+51 999 888 777',
06  isoCountryCode: 'PE'
07});

Campo	Tipo	Descripción
`name`	`string`	Nombre del usuario
`lastname`	`string`	Apellido
`email`	`string`	Email. Si no tiene un formato válido se ignora
`phone`	`string`	Teléfono con código de país. Se guardan solo los digitos
`isoCountryCode`	`string`	Código ISO del país (`PE`, `MX`, `CO`, ...)

Solo se completan datos vacios: si el contacto ya tiene nombre, email o teléfono, no se sobrescriben.
Si envías name o email, el widget omite el formulario de registro (formWidget).
Tener el email del contacto permite enviarle el resumen de la conversación por correo al solucionar el chat (ver Widget IA).

identify no autentica al usuario: solo completa los datos del contacto asociado a la sesión del navegador. No envies información sensible.

Eventos

Suscribete con PlzWidget.on(evento, callback). El método devuelve una función para cancelar la suscripción.

Evento	Datos del callback	Cuando se dispara
`ready`	—	La configuración del agente término de cargar
`open`	—	El widget se abre
`close`	—	El widget se cierra
`message`	`{ id, text, type, fromHuman, senderName }`	Llega un mensaje del agente IA o de un asesor
`unreadCountChange`	`{ count }`	Cambia la cantidad de mensajes sin leer

En el evento message, fromHuman es true cuando el mensaje lo escribio un asesor de tu equipo desde el CRM, y senderName trae su nombre.

Ejemplo: contador de no leidos en tu propio botón

01window.PlzWidgetOnLoad = function (PlzWidget) {
02  PlzWidget.hideLauncher();
03 
04  var badge = document.getElementById('chat-badge');
05  PlzWidget.on('unreadCountChange', function (data) {
06    badge.textContent = data.count > 0 ? data.count : '';
07  });
08 
09  document.getElementById('chat-button').addEventListener('click', function () {
10    PlzWidget.toggle();
11  });
12};

Ejemplo: enviar eventos a tu analitica

01window.PlzWidgetOnLoad = function (PlzWidget) {
02  PlzWidget.on('open', function () {
03    gtag('event', 'chat_open');
04  });
05 
06  var unsubscribe = PlzWidget.on('message', function (msg) {
07    if (msg.fromHuman) gtag('event', 'chat_human_reply');
08  });
09 
10  // Mas adelante, para dejar de escuchar:
11  // unsubscribe();
12};

Tipos TypeScript

Si tu sitio usa TypeScript, puedes declarar la API así:

01interface PlzWidgetIdentifyData {
02  name?: string;
03  lastname?: string;
04  email?: string;
05  phone?: string;
06  isoCountryCode?: string;
07}
08 
09interface PlzWidgetMessage {
10  id: string;
11  text: string;
12  type: string;
13  fromHuman: boolean;
14  senderName: string | null;
15}
16 
17interface PlzWidgetApi {
18  open(): void;
19  close(): void;
20  toggle(): void;
21  isOpen(): boolean;
22  sendMessage(text: string): void;
23  identify(data: PlzWidgetIdentifyData): void;
24  hideLauncher(): void;
25  showLauncher(): void;
26  getUnreadCount(): number;
27  on(event: 'ready' | 'open' | 'close', cb: () => void): () => void;
28  on(event: 'message', cb: (msg: PlzWidgetMessage) => void): () => void;
29  on(event: 'unreadCountChange', cb: (data: { count: number }) => void): () => void;
30}
31 
32declare global {
33  interface Window {
34    PlzWidget?: PlzWidgetApi;
35    PlzWidgetOnLoad?: (api: PlzWidgetApi) => void;
36  }
37}