API de JavaScript para chat en vivo
Usa la API de JavaScript de onWebChat para personalizar tu widget de chat y automatizar flujos de chat. Puedes pasar datos del visitante, definir el idioma del widget, maximizar u ocultar el widget y mucho más.
Por ejemplo, puedes enviar los datos del visitante al chat, definir el idioma por página o abrir el widget programáticamente cuando el usuario hace clic en un botón.
Añade el código de la API justo debajo del script del widget de chat, como se muestra a la derecha.
<script type='text/javascript'>
/* Paste your onWebChat widget installation snippet from the dashboard here. */
</script>
<script type='text/javascript'>
/* Add your JavaScript API calls below, for example onWebChat.set() or onWebChat.get() */
</script>
Definir información del visitante
Puedes definir los datos del visitante antes o durante una sesión de chat. Por ejemplo, definir el nombre ayuda a tu equipo a identificar contactos en la lista de visitantes.
Usa estas llamadas a la API para definir el nombre, el correo electrónico, el teléfono y las notas del visitante:
onWebChat.set("name","Sarah Chen");
onWebChat.set("email","sarah.chen@example.com");
onWebChat.set("phone","+1 555 010 0142");
onWebChat.set("notes","Returning visitor, requested an Enterprise trial");
Obtener información del visitante
Puedes leer el nombre, el correo electrónico, el teléfono y las notas del visitante siempre que esos datos se hayan facilitado mediante esta API de JavaScript, se hayan recogido en el formulario pre-chat o los hayan actualizado los agentes en el panel.
Llama a estas funciones cuando el widget esté completamente cargado. Ejemplo:
onWebChat.set("onWebChatLoaded", function() { console.log("visitor name: " + onWebChat.get("name")); });
onWebChat.get("name");
onWebChat.get("email");
onWebChat.get("phone");
onWebChat.get("notes");
Definir idioma del widget
Puedes definir el idioma del widget con el código de cualquier idioma activado en tu panel.
Por ejemplo, usa "en" para inglés, "es" para español y "fr" para francés. Si el código indicado no está activado, el widget usa tu idioma predeterminado. Sin esta llamada, el widget usa el idioma del navegador del visitante si tienes activada esa opción. Puedes gestionar los idiomas activados y el idioma predeterminado en Configuración > Widget > Idiomas.
Códigos de idioma disponibles:
onWebChat.set("language","es");
Definir aspecto del widget
Puedes controlar la visibilidad del widget y si está abierto o cerrado:
Usa el parámetro max con 0 para minimizar o 1 para maximizar el widget.
Para ocultar el widget por completo, usa el parámetro show con el valor 0. Usa 1 para mostrarlo de nuevo.
onWebChat.set("max",1);
onWebChat.set("show",0);
Definir tamaño del widget
En una página concreta, puedes mostrar el widget en cualquiera de los tres tamaños de Configuración > Widget > Configuración del widget, sin cambiar el tamaño guardado en tu cuenta.
Usa el parámetro size con "standard" (el tamaño Pequeño del panel), "large" (Grande) o "xlarge" (Extra grande). Es útil en páginas con poco espacio libre o en una landing page donde quieres un widget más grande.
Importante: añade esta llamada justo debajo del script del widget, antes de que el widget cargue. El widget se crea una sola vez, al cargar, así que un tamaño definido después se ignora.
onWebChat.set("size","standard");
onWebChat.set("size","large");
onWebChat.set("size","xlarge");
Cambiar textos del widget
Puedes sustituir los textos del widget en una página concreta, por ejemplo un saludo distinto en tu página de precios. Los nuevos textos se usan solo en esa página y no se guardan en tu panel.
Usa el parámetro texts con un objeto con los campos que quieres cambiar, como max_title, max_subtitle, min_online, min_offline, off_title, off_subtitle, off_msg o prechat_msg.
Un texto indicado como cadena se usa en todos los idiomas de tu widget. Para cambiar un solo idioma, pasa un objeto con los códigos de idioma, como en el segundo ejemplo.
Puedes llamarla debajo del script del widget, antes de que cargue, o en cualquier momento después: el widget se vuelve a dibujar con los nuevos textos.
onWebChat.set("texts",{
max_title: "Need help?",
max_subtitle: "We usually reply in a minute"
});
onWebChat.set("texts",{
min_online: { en: "Chat with us", es: "Chatea con nosotros" }
});
Set Widget Colors
On a specific page, you can give the widget header one color while your chat is online and another while it is offline. Use the onlineColor and offlineColor parameters with any CSS color, such as "#2e7d32".
The colors are used on that page only and do not change the color saved in Settings > Widget > Widget settings. You can set them before the widget loads or any time after that. The offline color is also used for the Send button of the offline form.
onWebChat.set("onlineColor","#2e7d32");
onWebChat.set("offlineColor","#757575");
Definir información de página
Puedes sobrescribir la URL y el título de la página actual que se envían al panel de onWebChat:
Usa el parámetro pageUrl para definir una URL personalizada. Es especialmente útil en aplicaciones de una sola página (SPA) o con enrutamiento personalizado, donde la URL del navegador no cambia.
Usa el parámetro pageTitle para definir un título personalizado que verán los agentes en lugar del título de la página del navegador.
onWebChat.set("pageUrl","https://www.example.com/checkout/step-2");
onWebChat.set("pageTitle","Checkout: shipping details");
Obtener estado del widget
Devuelve "online" u "offline" según la disponibilidad actual de tu chat.
Llama a esta función cuando el widget esté cargado. Ejemplo:
onWebChat.set("onWebChatLoaded", function() { console.log("chat status: " + onWebChat.get("status")); });
onWebChat.get("status");
Obtener estado de conexión
Devuelve true si el widget de chat tiene una conexión socket activa con el servidor, o false en caso contrario.
onWebChat.get("isConnected");
Obtener estado abierto/cerrado del widget
Devuelve true si el widget de chat está actualmente maximizado (abierto), o false si está minimizado (cerrado).
onWebChat.get("isMaximized");
Obtener ID del diálogo
Devuelve el ID del diálogo activo actual, o 0 si no hay ninguna sesión de chat activa. Es el mismo ID que chat_id en los datos de los webhooks, así que resulta útil para integraciones que necesitan vincular una sesión de chat con un CRM o un sistema de tickets.
onWebChat.get("dialogId");
Enviar mensaje
Puedes enviar un mensaje de chat en nombre del visitante de forma programática. Útil para crear flujos de ayuda contextuales, como enviar «Necesito ayuda con mi pedido» cuando el visitante hace clic en un botón concreto.
El mensaje aparece en el chat exactamente como si lo hubiera escrito el visitante, y se abre la ventana de chat. El widget debe estar completamente cargado y conectado antes de poder enviar un mensaje. Para evitar abusos, por esta vía el widget envía como máximo 3 mensajes por segundo, 8 por minuto y 30 por hora.
onWebChat.set("sendMessage","I need help with my order");
Definir departamento
Puedes preseleccionar un departamento para el visitante según la página en la que está. Por ejemplo, puedes dirigir automáticamente a los visitantes de tu página de precios al departamento «Ventas» y a los de tu página de ayuda a «Soporte».
Puedes pasar el nombre del departamento (como texto) o su ID (como número). Si usas el nombre, debe coincidir exactamente con uno de los departamentos configurados en tu panel.
Puedes encontrar el ID del departamento en tu panel: ve a Configuración > Equipo > Departamentos y haz clic en un departamento. El ID aparece junto al nombre del departamento.
No necesitas activar la opción de departamentos en el formulario pre-chat: asignar el departamento con la API de JavaScript funciona por sí solo.
Si ningún agente del departamento seleccionado está en línea, el mensaje llega a todos los agentes conectados. Además, cuando el departamento se asigna mediante la API, el chatbot de IA (si está activado) no responde en ese chat.
Para más información sobre departamentos, consulta nuestra guía de departamentos.
onWebChat.set("department","Sales");
onWebChat.set("department",1333);
Funciones de callback
Puedes ejecutar funciones de callback cuando ocurren determinados eventos del chat:
onClick se ejecuta cuando el visitante hace clic en el widget de chat.
onMaximize se ejecuta cuando el widget se maximiza (se abre).
onMinimize se ejecuta cuando el widget se minimiza (se cierra).
onTrigger se ejecuta cuando se activa un disparador de compromiso o de intención de salida, incluso mientras el widget está oculto con show en 0.
onStartWriting se ejecuta cuando el visitante empieza a escribir un mensaje (una vez por sesión del navegador).
onNewMessage se ejecuta cuando se envía o recibe un nuevo mensaje. El callback recibe dos argumentos: el texto del mensaje y quién lo envió ("visitor", "agent" o "bot").
onEndChat se ejecuta cuando termina la sesión de chat. El callback recibe un argumento que indica quién la terminó ("visitor", "agent" o "bot").
onChatStatusChange se ejecuta cuando cambia el estado del widget de chat. El callback recibe un argumento con el nuevo estado ("online" u "offline").
onWebChatLoaded se ejecuta cuando el widget de chat termina de cargar.
onWebChat.set("onClick",function(){ alert('chat widget is clicked'); });
onWebChat.set("onMaximize",function(){ alert('chat maximized'); });
onWebChat.set("onMinimize",function(){ alert('chat minimized'); });
onWebChat.set("onTrigger",function(){ alert('trigger activated'); });
onWebChat.set("onStartWriting",function(){ alert('visitor is writing'); });
onWebChat.set("onNewMessage",function(msg, by){
console.log('new message by ' + by + ': ' + msg);
});
onWebChat.set("onEndChat",function(endedBy){
console.log('chat ended by ' + endedBy);
});
onWebChat.set("onChatStatusChange",function(status){
console.log('agents are now ' + status);
});
onWebChat.set("onWebChatLoaded",function(){ alert('chat widget is loaded'); });