JavaScript SDK: controlla il widget di chat dalla tua pagina

Lo script di incorporamento aggiunge window.IntoChat alla tua pagina. Con questo oggetto il tuo JavaScript può aprire e chiudere la bolla della chat, dire all'agente chi è il visitatore che ha effettuato l'accesso, cambiare la lingua del widget e reagire a ciò che succede nella chat.

Prima di iniziare

L'SDK è incluso nel tag script. Non c'è nient'altro da installare:

<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 esiste non appena lo script è stato eseguito, prima che la finestra della chat sia caricata. Le chiamate fatte presto attendono che la bolla e la finestra della chat siano pronte, quindi puoi chiamare qualsiasi metodo subito dopo lo snippet.

L'SDK funziona solo con la bolla della chat aggiunta dallo script. Un iframe incorporato o un link diretto non ha nella pagina uno script con cui comunicare.

Metodi

open, close e toggle

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

Aprire la chat in questo modo conta come un uso della chat da parte del visitatore, quindi il pop-up di benvenuto e l'apertura automatica non compaiono più durante quella visita.

IntoChat.open() funziona anche per i visitatori che non vedono la bolla a causa di Show the chat to a share of visitors. Il rilascio graduale nasconde solo la bolla e i suoi inviti, quindi un pulsante "Chatta con noi" sulla tua pagina apre comunque la chat per tutti. Per questi visitatori la finestra di chat viene caricata la prima volta che si apre. Con Center Stage, open() apre la finestra centrata e close() la chiude come fa 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 è il modo in cui funziona la verifica dell'identità. userHash è l'HMAC-SHA256 di userId, con il segreto di identità del tuo agente come chiave, calcolato sul tuo server, così nessuno può fingersi un altro utente. Senza un userHash valido il visitatore resta semplicemente non verificato.

identify restituisce true quando i dati rispettano queste regole, e false (con un avviso nella console del browser) quando non le rispettano. La validità della firma viene controllata solo dal server di intoCHAT, quando il visitatore invia un messaggio.

Chiama identify a ogni caricamento di pagina finché il visitatore ha effettuato l'accesso. Se identifichi un utente diverso dall'ultimo su questo browser, si avvia automaticamente una nuova chat, così una persona non vede mai la conversazione di un'altra. Un visitatore che ha chattato prima di accedere mantiene quella chat.

reset

IntoChat.reset();

Chiamalo quando il visitatore esce dal suo account. Dimentica l'identità e avvia una nuova chat vuota. Viene svuotato anche l'elenco delle chat precedenti su questo browser; le conversazioni restano nella tua dashboard.

setLanguage

IntoChat.setLanguage("de");

Cambia i testi del widget (pulsanti, etichette, avvisi) in inglese (en), tedesco (de), francese (fr), italiano (it) o spagnolo (es). Un codice con regione come de-CH vale come de. Qualsiasi altro codice restituisce false. Prende il posto dell'attributo lang della tua pagina, quindi non ha effetto se hai scelto una lingua fissa per il widget nella scheda Appearance. Non cambia i tuoi messaggi di benvenuto né la lingua in cui risponde l'agente.

on e off

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

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

on restituisce anche una funzione che rimuove il listener. Un listener che genera un errore non blocca gli altri; l'errore viene registrato nella console.

Eventi

Ogni callback riceve un oggetto. Contiene sempre chatbotId, l'agente da cui proviene l'evento.

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

In una chat temporanea gli eventi lead e booking non partono, perché lì modulo lead e prenotazione non vengono proposti. I contatti che un visitatore scrive nella chat, invece di usare il modulo, non generano lead.

Chiamarlo prima che lo script sia caricato

Se il tuo codice può essere eseguito prima dello snippet, aggiungi le chiamate a window.IntoChatQueue. Ogni voce è il nome del metodo seguito dai suoi argomenti:

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

Lo script esegue la coda quando si carica. Le voci aggiunte dopo vengono eseguite subito.

Più agenti nella stessa pagina

Con gli snippet di più agenti nella stessa pagina, ogni chiamata vale per tutte le loro bolle, e il chatbotId di ogni evento indica da quale agente proviene. Ogni agente ha il suo segreto di identità, quindi un userHash verifica il visitatore solo per l'agente il cui segreto l'ha firmato.

Il rapporto con IntoChatActions

window.IntoChatActions è separato e funziona esattamente come prima: esegue le azioni lato client quando l'agente le chiama. IntoChat serve al tuo codice per controllare il widget. Puoi usarli insieme. Quando il visitatore è verificato, anche l'handler di un'azione lato client lo riceve come 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 };
});

Sicurezza

La finestra della chat gira sul dominio di intoCHAT. Lo script nella tua pagina scambia messaggi solo con la propria finestra di chat, e solo mentre quella finestra mostra intoCHAT: altri frame nella tua pagina non possono ricevere l'identità del visitatore, inviare eventi falsi o avviare azioni. Gli eventi contengono ciò che il visitatore ha scritto e le risposte dell'agente, quindi trattali come qualsiasi altro dato dei visitatori nella tua pagina.