SDK de JavaScript: controla el widget de chat desde tu página

El script de inserción añade window.IntoChat a tu página. Con él, tu propio JavaScript puede abrir y cerrar la burbuja de chat, decirle al agente quién es el visitante con sesión iniciada, cambiar el idioma del widget y reaccionar a lo que ocurre en el chat.

Antes de empezar

El SDK viene con la etiqueta script. No hay nada más que instalar:

<script src="https://www.intochat.ai/api/embed.js" data-chatbot-id="YOUR_AGENT_ID"></script>
<script>
  window.IntoChat.on("reply", function (event) {
    console.log("The agent replied:", event.text);
  });
</script>

window.IntoChat existe en cuanto se ha ejecutado el script, antes de que cargue la ventana del chat. Las llamadas que hagas antes esperan a que la burbuja y la ventana del chat estén listas, así que puedes llamar a cualquier método justo después del snippet.

El SDK solo funciona con la burbuja de chat que añade el script. Un iframe en la página o un enlace directo no tiene ningún script en la página con el que comunicarse.

Métodos

open, close y toggle

<button type="button" onclick="IntoChat.open()">Chat with us</button>

Abrir el chat de esta forma cuenta como que el visitante usa el chat, así que la ventana emergente de bienvenida y la apertura automática ya no aparecen durante esa visita.

IntoChat.open() también funciona para los visitantes que no ven la burbuja por Show the chat to a share of visitors. El despliegue solo oculta la burbuja y sus invitaciones, así que un botón «Chatea con nosotros» en tu página sigue abriendo el chat para todos. Para esos visitantes, la ventana del chat se carga la primera vez que se abre. Con Center Stage, open() abre la ventana centrada y close() la cierra igual que Esc.

identify

IntoChat.identify({
  userId: "4711",                  // required: the user's id on your site
  userHash: "9f2c…",               // required: computed on your server
  name: "Ada Lovelace",            // optional
  email: "ada@example.com",        // optional
  metadata: { plan: "pro", seats: 3 } // optional
});

identify es la base de la verificación de identidad. userHash es el HMAC-SHA256 de userId, con el secreto de identidad de tu agente como clave y calculado en tu servidor, para que nadie pueda hacerse pasar por otro usuario. Sin un userHash válido, el visitante simplemente sigue sin verificar.

identify devuelve true cuando los datos cumplen estas reglas, y false (con un aviso en la consola del navegador) cuando no. Si la firma es válida solo lo comprueba el servidor de intoCHAT, cuando el visitante envía un mensaje.

Llama a identify en cada carga de página mientras el visitante tenga la sesión iniciada. Identificar a un usuario distinto del último en este navegador empieza automáticamente un chat nuevo, así que una persona nunca ve la conversación de otra. Un visitante que chateó antes de iniciar sesión conserva ese chat.

reset

IntoChat.reset();

Llámalo cuando el visitante cierre sesión. Olvida la identidad y empieza un chat nuevo y vacío. También se vacía la lista de chats anteriores en este navegador; las conversaciones en sí se quedan en tu panel.

setLanguage

IntoChat.setLanguage("de");

Cambia los textos propios del widget (botones, etiquetas, avisos) a inglés (en), alemán (de), francés (fr), italiano (it) o español (es). Un código regional como de-CH cuenta como de. Cualquier otro código devuelve false. Sustituye al atributo lang de tu página, así que no tiene efecto si elegiste un idioma fijo para el widget en la pestaña Appearance. No cambia tus mensajes de bienvenida ni el idioma en que responde el agente.

on y off

function onReply(event) {
  analytics.track("chat_reply", { agent: event.chatbotId });
}

IntoChat.on("reply", onReply);
// later
IntoChat.off("reply", onReply);

on también devuelve una función que quita el listener. Un listener que lanza un error no detiene a los demás; el error se registra en la consola.

Eventos

Cada callback recibe un objeto. Siempre tiene chatbotId, el agente del que viene el evento.

IntoChat.on("live_chat", function (event) {
  if (event.status === "active") document.title = "A team member is chatting with you";
});

En un chat temporal no se disparan lead ni booking, porque ahí no se ofrecen. Los datos de contacto que un visitante escribe en el chat, en lugar de usar el formulario, no disparan lead.

Llamarlo antes de que cargue el script

Si tu código puede ejecutarse antes del snippet, añade las llamadas a window.IntoChatQueue. Cada entrada es el nombre del método seguido de sus argumentos:

<script>
  window.IntoChatQueue = window.IntoChatQueue || [];
  window.IntoChatQueue.push(["identify", { userId: "4711", userHash: "9f2c…" }]);
  window.IntoChatQueue.push(["on", "lead", function () { console.log("New lead"); }]);
</script>
<script src="https://www.intochat.ai/api/embed.js" data-chatbot-id="YOUR_AGENT_ID"></script>

El script aplica la cola al cargar. Lo que se añada después se ejecuta al momento.

Varios agentes en una página

Con los snippets de varios agentes en una página, cada llamada se aplica a todas sus burbujas, y el chatbotId de cada evento indica de qué agente viene. Cada agente tiene su propio secreto de identidad, así que un userHash solo verifica al visitante para el agente cuyo secreto lo firmó.

Relación con IntoChatActions

window.IntoChatActions es independiente y funciona exactamente igual que antes: ejecuta las acciones del lado del cliente cuando el agente las llama. IntoChat sirve para que tu propio código controle el widget. Los dos se pueden usar juntos. Cuando el visitante está verificado, un manejador de una acción del lado del cliente también lo recibe como context.user:

IntoChatActions.register("Get_cart", async function (args, context) {
  // context.user: { id, name, email, metadata }, only for a verified visitor
  return { items: window.myStore.cart.items };
});

Seguridad

La ventana del chat se ejecuta en el dominio de intoCHAT. El script de tu página solo intercambia mensajes con su propia ventana del chat, y solo mientras esa ventana muestra intoCHAT: otros frames de tu página no pueden recibir la identidad del visitante, enviar eventos falsos ni activar acciones. Los eventos llevan lo que escribió el visitante y las respuestas del agente, así que trátalos como cualquier otro dato de visitantes en tu página.