JavaScript-API: Agent per Code steuern

Mit der JavaScript-API steuerst Du Deinen LeadWin-Agenten aus Deiner eigenen Website. Eigene Schaltflächen öffnen den Chat direkt beim Kontaktformular oder bei der Terminbuchung, und Dein Dark Mode und Dein Sprachumschalter schalten den Agenten mit um. Die Seite im Dashboard ist eine Anleitung mit Codebeispielen zum Kopieren, sie ändert keine Einstellung.

Auf einen Blick

Du findest die Seite im LeadWin-Dashboard unter Auftritt → API.
Die API gibt es in jedem Abo, auch in Free. Welche Bereiche sie öffnen kann, hängt aber von Deinem Abo ab, siehe Abos im Vergleich.
Voraussetzung ist der Code aus der Installation auf Deiner Website. Diesen Code erhältst Du erst, wenn der Auftragsverarbeitungsvertrag abgeschlossen ist. Mit einer Registrierung auf leadwin.ai ist er das schon, kommst Du von Feedbax, als Anbieter oder Auftraggeber, stimmst Du ihm unter Datenschutz zu.
Schaltflächen mit dem Attribut data-leadwin-open funktionieren ohne eigenes JavaScript, in jedem CMS.
Jeder Aufruf gilt nur für den einzelnen Besucher und ändert nie Deine Einstellungen im Dashboard.
Die Seite sehen Inhaber und Admins. Wer welche Rolle hat, legst Du unter Team fest.

Die Karte JavaScript-API mit Einleitung und dem Grundgerüst als Codebeispiel mit der Schaltfläche Code kopieren

So funktioniert es

Der Code aus der Installation lädt auf Deiner Website die Funktion LeadWin. Du rufst sie mit einem Befehl und einem Wert auf, zum Beispiel LeadWin('open', 'lead'). Groß- und Kleinschreibung des Befehls spielen keine Rolle. Einen unbekannten Befehl ignoriert LeadWin, und die API wirft nie einen Fehler in Deine Seite.

Dein LeadWin-Agent lädt erst, wenn Deine Seite fertig geladen ist. Ruft Dein eigenes JavaScript ihn vorher auf, fängt das Grundgerüst den Aufruf auf und reicht ihn weiter, sobald der Agent da ist. Umgekehrt verändert Dein LeadWin-Agent an Deiner Seite nichts. Er meldet nur, wenn sich der Chat öffnet oder schließt. Was Deine Seite daraus macht, entscheidest Du.

Diese Befehle gibt es:

Befehl	Wert	Wirkung
open	keiner, lead, booking, helpcenter oder profile	Öffnet den Chat, auf Wunsch direkt in einem Bereich
close	keiner	Schließt den Chat
toggle	keiner	Öffnet einen geschlossenen und schließt einen offenen Chat
ask	eine Frage mit 1 bis 1.000 Zeichen	Öffnet den Chat und stellt die Frage im Namen des Besuchers
theme	dark, light oder auto	Schaltet zwischen hellem und dunklem Design um, nur mit dem Farbschema API
language	de, en, fr, nl oder auto	Schaltet die Sprache der Oberfläche um
article	Schlüssel eines Hilfe-Artikels	Öffnet den Chat direkt bei diesem Artikel
consent	granted oder denied	Gibt die Entscheidung Deines Cookie-Banners weiter

Das Grundgerüst einbauen

Das Grundgerüst brauchst Du nur, wenn Du LeadWin aus eigenem JavaScript aufrufst. Für Schaltflächen mit data-leadwin-open brauchst Du es nicht.

Öffne Auftritt → API und klicke in der ersten Karte auf Code kopieren. Die Meldung Code kopiert bestätigt es.
Füge den Code einmal in den Head-Bereich Deiner Seite ein, oberhalb der Skripte, die LeadWin aufrufen.
Lass den Code aus der Installation unverändert. Wo das Grundgerüst im Verhältnis zu ihm steht, spielt keine Rolle.

<script>
    globalThis.LeadWin ??= (...args) =>
        (globalThis.LeadWin.q ??= []).push(args);
</script>

Den Chat öffnen und schließen

Mit open klappst Du den Chat auf. Gibst Du einen Bereich mit, öffnet er sich direkt dort:

lead: das Kontaktformular. Was Besucher dort eintragen, landet bei Deinen Anfragen.
booking: die Terminbuchung. Sie muss eingerichtet sein.
helpcenter: Dein Hilfe-Center. Dafür brauchst Du ein aktives Hilfe-Center aus Deiner Wissensdatenbank.
profile: die Profilansicht Deines Unternehmens aus Deinem Profil.

Bietet Dein LeadWin-Agent einen Bereich nicht an, öffnet sich der Chat. close schließt ihn, toggle wechselt zwischen offen und geschlossen.

LeadWin('open');
LeadWin('open', { screen: 'lead' });
LeadWin('open', { screen: 'booking' });
LeadWin('close');
LeadWin('toggle');

Die Karte Widget öffnen mit den Befehlen open, close und toggle als Codebeispiel

Schaltflächen ohne JavaScript einbauen

Jedes Element mit dem Attribut data-leadwin-open öffnet beim Klick den Chat. Als Wert trägst Du den Bereich ein. Ohne Wert öffnet sich der Chat selbst. Das funktioniert in jedem CMS, auch für Elemente, die erst später auf die Seite kommen, und braucht weder das Grundgerüst noch eigenes JavaScript.

<button data-leadwin-open="lead">Team kontaktieren</button>
<button data-leadwin-open>Chat öffnen</button>

Eine Frage im Namen des Besuchers stellen

Mit ask öffnest Du den Chat und stellst sofort eine Frage, so als hätte der Besucher sie getippt. Das passt zu Schaltflächen, hinter denen immer dieselbe Frage steht, etwa „Was kostet das?“.

Die Frage hat 1 bis 1.000 Zeichen. Ist sie leer oder länger, passiert nichts.
Sie landet in dem Gespräch, das der Besucher gerade offen hat. Mit newChat: true beginnt sie ein neues.
Schreibt Dein LeadWin-Agent gerade eine Antwort, wird der Klick ignoriert.
Die Frage ist eine normale Nachricht des Besuchers. Ein neues Gespräch zählt deshalb gegen Dein Gesprächskontingent.

LeadWin('ask', 'Was kostet das?');
LeadWin('ask', { prompt: 'Was kostet das?' });
LeadWin('ask', { prompt: 'Was kostet das?', newChat: true });

Die Karte Frage stellen mit drei Beispielen für den Befehl ask

Dark Mode koppeln

Schaltet Deine Website zwischen hell und dunkel um, schaltet theme Deinen LeadWin-Agenten mit um. Das wirkt nur, wenn unter Darstellung das Farbschema API gewählt ist. Bis zum ersten Aufruf zeigt Dein LeadWin-Agent dann das helle Design. Der Aufruf gilt nur für den Besucher, der ihn auslöst. Mit auto setzt Du ihn zurück.

LeadWin('theme', 'dark');
LeadWin('theme', 'light');
LeadWin('theme', 'auto');

Die Karte Dark Mode koppeln mit drei Beispielen für den Befehl theme

Sprache koppeln

Bei einem normalen Seitenwechsel liest Dein LeadWin-Agent die Sprachangabe Deiner Seite ohnehin neu. Den Befehl language brauchst Du nur, wenn Besucher die Sprache wechseln, ohne dass die Seite neu lädt. Er nimmt de, en, fr und nl an, auch als Ländercode wie de-DE. Es wirken nur Sprachen, die unter Sprache eingeschaltet sind. Ist der Chat offen, lädt er in der neuen Sprache neu, und das Gespräch geht weiter. Mit auto gibst Du die Entscheidung an die Sprachangabe Deiner Seite zurück.

LeadWin('language', 'en');
LeadWin('language', 'auto');

Auf das Öffnen reagieren

Öffnet oder schließt sich der Chat, löst Dein LeadWin-Agent auf Deiner Seite das Ereignis leadwin:panel aus. In event.detail.open steht true oder false. Das Ereignis kommt nur bei einer echten Änderung, nicht bei jedem Befehl. Es steigt im Dokument auf, Du kannst also auch auf window lauschen. So blendest Du zum Beispiel eine klebende Leiste aus oder hältst ein Video an, solange der Chat offen ist.

document.addEventListener('leadwin:panel', (event) =>
    document.body.classList.toggle('leadwin-open', event.detail.open));

Weitere Befehle und Attribute

Diese Möglichkeiten stehen nicht auf der Seite im Dashboard, funktionieren aber genauso:

LeadWin('article', 'schluessel'): öffnet den Chat direkt bei einem Artikel aus Deinem Hilfe-Center. Als Schlüssel nimmst Du den Slug aus der Adresse des Artikels oder seine GUID. Erlaubt sind Buchstaben, Ziffern, Bindestrich und Unterstrich, höchstens 300 Zeichen.
LeadWin('consent', 'granted'): gibt die Entscheidung Deines Cookie-Banners weiter. Wie das mit der Einwilligung zusammenhängt, steht in Datenschutz.
data-lang: Am Code aus der Installation legt dieses Attribut die Sprache der Seite fest, zum Beispiel data-lang="en". Es geht dem Attribut lang im html-Tag vor.
data-title: Am Code aus der Installation legt dieses Attribut fest, wie Screenreader den Launcher vorlesen. Ohne Angabe heißt er Chat.

Beide Attribute setzt Du in das öffnende script-Tag, das schon data-key enthält.

Was Dein Abo enthält

Die JavaScript-API gibt es in jedem Abo, von Free bis Scale. Was ein Befehl öffnen kann, hängt davon ab, was Dein Abo enthält: Die Terminbuchung gibt es ab Basic, das eigene Hilfe-Center ab Pro. Das Farbschema API gibt es in jedem Abo. Mit Feedbax Business gelten die Grenzen von Basic, mit Premium die von Pro und mit Enterprise die von Scale. Mehr dazu in LeadWin im Feedbax-Abo.

Häufige Fragen

Wie öffnet meine Schaltfläche Kontakt das LeadWin-Formular?

Ergänze an der Schaltfläche das Attribut data-leadwin-open="lead". Eigenes JavaScript brauchst Du dafür nicht.

Kann eine Schaltfläche direkt die Terminbuchung öffnen?

Ja, mit data-leadwin-open="booking" oder LeadWin('open', { screen: 'booking' }). Die Terminbuchung muss eingerichtet sein, sonst öffnet sich der Chat.

Meine Website hat einen Dark Mode. Wie folgt der Chat?

Stelle unter Darstellung das Farbschema auf API und rufe LeadWin('theme', 'dark') oder LeadWin('theme', 'light') auf, sobald Deine Website umschaltet.

LeadWin('theme', 'dark') tut nichts. Warum?

Das Farbschema steht nicht auf API. Der Befehl wirkt nur dann.

Brauche ich das Grundgerüst?

Nur wenn Dein eigenes JavaScript LeadWin aufruft, womöglich bevor Dein LeadWin-Agent geladen ist. Für Schaltflächen mit data-leadwin-open nicht.

Kann ich reagieren, wenn der Chat aufgeht?

Ja. Lausche auf das Ereignis leadwin:panel und lies event.detail.open.

Kann ich eine Frage im Namen des Besuchers senden?

Ja, mit LeadWin('ask', 'Deine Frage') und bis zu 1.000 Zeichen. Die Frage landet im offenen Gespräch, außer Du gibst newChat: true mit.

Funktioniert LeadWin('language', 'fr'), wenn Französisch nicht eingeschaltet ist?

Nein. Der Befehl nimmt nur Sprachen an, die unter Sprache eingeschaltet sind.