JavaScript-SDK: das Chat-Widget von deiner Seite aus steuern

Das Embed-Script fügt deiner Seite window.IntoChat hinzu. Damit kann dein eigenes JavaScript die Chat-Bubble öffnen und schließen, dem Agenten mitteilen, wer der angemeldete Besucher ist, die Sprache des Widgets wechseln und auf das reagieren, was im Chat passiert.

Bevor du loslegst

Das SDK kommt mit dem Script-Tag. Du musst nichts weiter installieren:

<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 steht bereit, sobald das Script gelaufen ist, noch bevor das Chatfenster geladen hat. Frühe Aufrufe warten, bis Launcher und Chatfenster bereit sind. Du kannst also jede Methode direkt nach dem Snippet aufrufen.

Das SDK funktioniert nur mit der Chat-Bubble, die das Script einfügt. Bei einem iframe oder einem Direktlink gibt es kein Script auf der Seite, mit dem es sprechen könnte.

Methoden

open, close und toggle

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

Öffnet sich der Chat auf diese Weise, zählt das so, als hätte der Besucher den Chat benutzt. Das Begrüßungs-Pop-up und das automatische Öffnen erscheinen danach während dieses Besuchs nicht mehr.

IntoChat.open() funktioniert auch für Besucher, die den Launcher wegen Den Chat nur einem Teil der Besucher zeigen nicht sehen. Der Rollout blendet nur den Launcher und seine Einladungen aus, ein Button „Chat mit uns“ auf deiner Seite öffnet den Chat also weiterhin für alle. Für diese Besucher wird das Chatfenster beim ersten Öffnen geladen. Mit Center Stage öffnet open() das zentrierte Fenster, und close() schließt es wie Esc.

identify

IntoChat.identify({
  userId: "4711",                  // Pflicht: die ID des Nutzers auf deiner Website
  userHash: "9f2c…",               // Pflicht: auf deinem Server berechnet
  name: "Ada Lovelace",            // optional
  email: "ada@example.com",        // optional
  metadata: { plan: "pro", seats: 3 } // optional
});

Über identify funktioniert die Identitätsprüfung. userHash ist das HMAC-SHA256 von userId mit dem Identitäts-Secret deines Agenten als Schlüssel, berechnet auf deinem Server, damit sich niemand als ein anderer Nutzer ausgeben kann. Ohne gültigen userHash bleibt der Besucher einfach unverifiziert.

identify gibt true zurück, wenn die Eingabe diese Regeln erfüllt, und false (mit einer Warnung in der Browserkonsole), wenn nicht. Ob die Signatur gültig ist, prüft erst der Server von intoCHAT, wenn der Besucher eine Nachricht sendet.

Rufe identify bei jedem Seitenaufruf auf, solange der Besucher angemeldet ist. Identifizierst du in diesem Browser einen anderen Nutzer als zuletzt, startet automatisch ein neuer Chat, damit niemand das Gespräch einer anderen Person sieht. Ein Besucher, der schon vor der Anmeldung gechattet hat, behält diesen Chat.

reset

IntoChat.reset();

Rufe es auf, wenn sich der Besucher abmeldet. Es vergisst die Identität und startet einen neuen, leeren Chat. Auch die Liste früherer Chats in diesem Browser wird geleert; die Gespräche selbst bleiben in deinem Dashboard.

setLanguage

IntoChat.setLanguage("de");

Wechselt die Texte des Widgets selbst (Buttons, Beschriftungen, Hinweise) auf Englisch (en), Deutsch (de), Französisch (fr), Italienisch (it) oder Spanisch (es). Ein Regionalcode wie de-CH zählt als de. Jeder andere Code gibt false zurück. Die Methode ersetzt das Attribut lang deiner Seite und hat daher keine Wirkung, wenn du im Tab Appearance eine feste Sprache für das Widget gewählt hast. Deine Begrüßungen und die Sprache, in der der Agent antwortet, ändert sie nicht.

on und off

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

IntoChat.on("reply", onReply);
// später
IntoChat.off("reply", onReply);

on gibt außerdem eine Funktion zurück, die den Listener entfernt. Ein Listener, der einen Fehler wirft, hält die anderen nicht auf; der Fehler landet in der Konsole.

Events

Jeder Callback bekommt ein Objekt. Es enthält immer chatbotId, den Agenten, von dem das Event kommt.

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

In einem temporären Chat werden lead und booking nicht ausgelöst, weil beides dort nicht angeboten wird. Kontaktdaten, die ein Besucher in den Chat tippt, statt das Formular zu nutzen, lösen kein lead aus.

Aufrufe, bevor das Script lädt

Kann dein Code vor dem Snippet laufen, leg Aufrufe in window.IntoChatQueue ab. Jeder Eintrag ist der Name der Methode, gefolgt von ihren Argumenten:

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

Das Script arbeitet die Warteschlange beim Laden ab. Spätere Einträge laufen sofort.

Mehrere Agenten auf einer Seite

Hast du Snippets für mehrere Agenten auf einer Seite, gilt jeder Aufruf für alle ihre Launcher, und die chatbotId jedes Events sagt, von welchem Agenten es kommt. Jeder Agent hat sein eigenes Identitäts-Secret, ein userHash verifiziert den Besucher also nur für den Agenten, dessen Secret ihn signiert hat.

Zusammenspiel mit IntoChatActions

window.IntoChatActions ist davon getrennt und funktioniert genau wie bisher: Es führt client-seitige Aktionen aus, wenn der Agent sie aufruft. IntoChat ist dafür da, dass dein eigener Code das Widget steuert. Beides lässt sich zusammen nutzen. Ist der Besucher verifiziert, bekommt auch ein Handler für eine client-seitige Aktion ihn als context.user:

IntoChatActions.register("Get_cart", async function (args, context) {
  // context.user: { id, name, email, metadata }, nur bei einem verifizierten Besucher
  return { items: window.myStore.cart.items };
});

Sicherheit

Das Chatfenster läuft auf der Domain von intoCHAT. Das Script auf deiner Seite tauscht Nachrichten nur mit seinem eigenen Chatfenster aus, und nur solange dieses Fenster intoCHAT zeigt: Andere Frames auf deiner Seite können weder die Identität des Besuchers empfangen noch gefälschte Events senden oder Aktionen auslösen. Events enthalten, was der Besucher getippt hat, und die Antworten des Agenten. Behandle sie also wie alle anderen Besucherdaten auf deiner Seite.