API JavaScript del Widget

Introduccion

Cuando el script del widget se carga en tu pagina, 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 sesion en tu sitio y reaccionar a lo que ocurre en la conversacion.

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

El script del widget se instala con defer, asi 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 configuracion del agente termino de cargar. Si te suscribes a ready cuando el widget ya estaba listo, el callback se ejecuta de inmediato.
Los metodos sendMessage e identify se pueden llamar antes de ready: quedan en cola y se ejecutan al cargar la configuracion.

Metodos

Metodo	Descripcion
`open()`	Abre el widget
`close()`	Cierra el widget
`toggle()`	Abre o cierra el widget segun su estado actual
`isOpen()`	Devuelve `true` si el widget esta abierto
`sendMessage(text)`	Abre el chat y envia `text` como si lo hubiera escrito el usuario
`identify(data)`	Registra los datos del usuario en el contacto (ver abajo)
`hideLauncher()`	Oculta el boton flotante del widget
`showLauncher()`	Vuelve a mostrar el boton flotante
`getUnreadCount()`	Devuelve la cantidad de mensajes sin leer
`on(evento, callback)`	Suscribe un callback a un evento. Devuelve una funcion para cancelar la suscripcion

Abrir el chat desde tu propio boton

html

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

Si prefieres usar solo tu boton, oculta el boton flotante del widget:

01PlzWidget.hideLauncher();

Enviar un mensaje

Util para iniciar una conversacion con contexto, por ejemplo desde la pagina de un producto:

01PlzWidget.sendMessage('Quiero informacion 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 envia el mensaje. Usa identify antes para omitir el formulario.

Identificar al usuario

Si el usuario ya inicio sesion en tu sitio, envia sus datos para que el contacto en el CRM quede con nombre, email y telefono:

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	Descripcion
`name`	`string`	Nombre del usuario
`lastname`	`string`	Apellido
`email`	`string`	Email. Si no tiene un formato valido se ignora
`phone`	`string`	Telefono con codigo de pais. Se guardan solo los digitos
`isoCountryCode`	`string`	Codigo ISO del pais (`PE`, `MX`, `CO`, ...)

Solo se completan datos vacios: si el contacto ya tiene nombre, email o telefono, no se sobrescriben.
Si envias name o email, el widget omite el formulario de registro (formWidget).
Tener el email del contacto permite enviarle el resumen de la conversacion por correo al solucionar el chat (ver Widget IA).

identify no autentica al usuario: solo completa los datos del contacto asociado a la sesion del navegador. No envies informacion sensible.

Eventos

Suscribete con PlzWidget.on(evento, callback). El metodo devuelve una funcion para cancelar la suscripcion.

Evento	Datos del callback	Cuando se dispara
`ready`	—	La configuracion del agente termino 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 boton

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 asi:

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}