Client-seitige Aktionen im Browser des Besuchers

Führe eine Aktion im Browser des Besuchers aus: mit einem JavaScript-Handler über IntoChatActions oder einem Endpunkt, der die Sitzung des Besuchers nutzt.

Eine client-seitige Aktion läuft auf der Seite, in die dein Agent eingebunden ist, nicht auf den Servern von intoCHAT. Damit erreichst du, was nur der Browser des Besuchers erreicht: einen Endpunkt deiner Website, der die Login-Sitzung des Besuchers braucht, oder Daten und Funktionen auf der Seite selbst.

Wann was passt

Du willst aufrufen	Verwende
Eine öffentliche API oder eine, die deinen geheimen Schlüssel braucht	Eine server-seitige API-Aktion
Einen Endpunkt auf deiner eigenen Domain, der die Cookies des Besuchers nutzt	Eine client-seitige Aktion, ohne zusätzlichen Code
Etwas auf der Seite, etwa den Warenkorb in JavaScript oder einen Dialog	Eine client-seitige Aktion mit registriertem Handler
Nichts: Besucher sollen nur eine deiner Seiten öffnen	Einen eigenen Button

Einrichten

Lege die Aktion im Tab Actions an, wie unter Eigene API-Aktionen beschrieben: URL, Eingaben und When to use.
Wähle in Schritt 3. When the AI should use it die Option Client-side action.
Speichere die Aktion.

So läuft ein Aufruf ab

Ruft der Agent eine client-seitige Aktion auf, gibt das Chat-Widget den Aufruf an das Embed-Script auf deiner Seite weiter:

Hat deine Seite unter dem Namen der Aktion einen Handler registriert, läuft dieser, und sein Rückgabewert geht an den Agenten.
Sonst ruft deine Seite die URL der Aktion von deiner eigenen Domain aus auf, mit den Cookies des Besuchers.

Jeder Aufruf hat 20 Sekunden Zeit. Danach meldet das Widget dem Agenten einen Fehler. Die Aktion braucht auch dann eine gültige öffentliche URL, wenn du nur einen Handler nutzt; ist ein Handler registriert, wird diese URL nicht aufgerufen.

Handler registrieren

Der Name des Handlers ist der Name der Aktion, in dem jedes Zeichen außer Buchstaben, Ziffern, _ und - durch _ ersetzt ist. Aus „Get cart“ wird also Get_cart. Der Editor zeigt den genauen Namen in seinem Codebeispiel.

window.IntoChatActions steht bereit, sobald das Script des Snippets gelaufen ist, noch bevor das Chat-Widget selbst geladen hat. Handler werden erst gesucht, wenn der Agent die Aktion aufruft. Ob du vor oder nach dem Laden des Widgets registrierst, macht also keinen Unterschied. Füge irgendwo nach dem Snippet ein Script ein:

<script src="https://www.intochat.ai/api/embed.js" data-chatbot-id="YOUR_AGENT_ID"></script>
<script>
  window.IntoChatActions.register("Get_cart", async function (args) {
    // args: die Eingaben, die der Agent ausgefüllt hat.
    // Gib etwas JSON-Serialisierbares zurück. Der Agent sieht es.
    return { items: window.myStore.cart.items };
  });
</script>

Code, der vor dem Snippet laufen kann, legt stattdessen Paare [name, handler] in window.IntoChatActionsQueue ab; das Embed-Script registriert sie beim Laden. Die meisten Seiten brauchen das nicht. Mit mehreren Agenten auf einer Seite teilen sich alle dieselben Handler.

Der Handler bekommt die Eingaben, die der Agent ausgefüllt hat, als args. Wirft er einen Fehler, geht dessen Meldung als fehlgeschlagener Aufruf an den Agenten. IntoChatActions.unregister(name) entfernt einen Handler, IntoChatActions.registered() listet die registrierten Namen auf.

Testen

Send test request im Editor läuft von den Servern von intoCHAT aus. Der Test prüft, ob die URL antwortet, und zeigt die Form der Antwort, sieht aber weder die Sitzungen deiner Besucher noch Handler auf deiner Seite. Im Playground gibt es keine Seite von dir um den Chat herum, daher ruft das Widget die URL selbst auf, ohne Cookies oder Handler deiner Website. Teste Handler und sitzungsbasierte Endpunkte auf einer Seite deiner Website, auf der das Widget installiert ist.