JavaScript-API für den Live-Chat
Nutzen Sie die onWebChat-JavaScript-API, um Ihr Chat-Widget anzupassen und Chat-Workflows zu automatisieren. Sie können Besucherdaten übergeben, die Widget-Sprache setzen, das Widget maximieren oder ausblenden und mehr.
Sie können beispielsweise Besucherdetails an den Chat senden, die Sprache pro Seite festlegen oder das Widget programmgesteuert öffnen, wenn ein Nutzer auf einen Button klickt.
Fügen Sie Ihren API-Code direkt unter dem Chat-Widget-Skript ein, wie rechts gezeigt.
<script type='text/javascript'>
/* Fügen Sie hier das Installations-Snippet des onWebChat-Widgets aus dem Dashboard ein. */
</script>
<script type='text/javascript'>
/* Fügen Sie unten Ihre JavaScript-API-Aufrufe hinzu, zum Beispiel onWebChat.set() oder onWebChat.get() */
</script>
Besucherinformationen setzen
Sie können Besucherdetails vor oder während einer Chat-Sitzung setzen. Wenn Sie zum Beispiel den Besuchernamen setzen, kann Ihr Team Kontakte in der Besucherliste leichter identifizieren.
Verwenden Sie die folgenden API-Aufrufe, um Name, E-Mail, Telefon und Notizen eines Besuchers zu setzen:
onWebChat.set("name","Sarah Chen");
onWebChat.set("email","sarah.chen@example.com");
onWebChat.set("phone","+1 555 010 0142");
onWebChat.set("notes","Returning visitor, requested an Enterprise trial");
Besucherinformationen abrufen
Sie können den Namen, die E-Mail-Adresse, die Telefonnummer und die Notizen des Besuchers auslesen, sofern diese Werte über diese JavaScript-API bereitgestellt, im Pre-Chat-Formular erfasst oder von Agenten im Dashboard aktualisiert wurden.
Rufen Sie diese Funktionen auf, nachdem das Widget vollständig geladen ist. Beispiel:
onWebChat.set("onWebChatLoaded", function() { console.log("visitor name: " + onWebChat.get("name")); });
onWebChat.get("name");
onWebChat.get("email");
onWebChat.get("phone");
onWebChat.get("notes");
Widget-Sprache setzen
Setzen Sie die Widget-Sprache mit dem Sprachcode einer beliebigen in Ihrem Dashboard aktivierten Sprache.
Verwenden Sie z. B. "de" für Deutsch, "en" für Englisch und "fr" für Französisch. Ist ein angegebener Sprachcode nicht aktiviert, verwendet das Widget Ihre Standardsprache. Ohne diesen Aufruf nutzt das Widget die Browsersprache des Besuchers, sofern Sie diese Option aktiviert haben. Ihre aktivierten Sprachen und die Standardsprache verwalten Sie unter Einstellungen > Widget > Sprachen.
Verfügbare Sprachcodes:
onWebChat.set("language","es");
Widget-Erscheinungsbild setzen
Sie können die Sichtbarkeit und den Öffnungszustand des Widgets steuern:
Verwenden Sie den Parameter max mit 0 zum Minimieren oder 1 zum Maximieren des Widgets.
Um das Widget vollständig auszublenden, verwenden Sie den Parameter show mit dem Wert 0. Verwenden Sie 1, um es wieder anzuzeigen.
onWebChat.set("max",1);
onWebChat.set("show",0);
Widget-Größe setzen
Auf einer bestimmten Seite können Sie das Widget in jeder der drei Größen aus Einstellungen > Widget > Widget-Einstellungen anzeigen, ohne die in Ihrem Konto gespeicherte Größe zu ändern.
Verwenden Sie den Parameter size mit "standard" (im Dashboard die Größe „Klein“), "large" oder "xlarge" („Sehr groß“). Das ist nützlich auf Seiten mit wenig Platz oder auf einer Landingpage, auf der Sie ein größeres Widget möchten.
Wichtig: Fügen Sie diesen Aufruf direkt unter dem Widget-Skript ein, bevor das Widget lädt. Das Widget wird einmal beim Laden aufgebaut, eine später gesetzte Größe wird ignoriert.
onWebChat.set("size","standard");
onWebChat.set("size","large");
onWebChat.set("size","xlarge");
Widget-Texte ändern
Sie können die Widget-Texte auf einer bestimmten Seite ersetzen, zum Beispiel eine andere Begrüßung auf Ihrer Preisseite. Die neuen Texte gelten nur für diese Seite und werden nicht im Dashboard gespeichert.
Verwenden Sie den Parameter texts mit einem Objekt der Felder, die Sie ändern möchten, etwa max_title, max_subtitle, min_online, min_offline, off_title, off_subtitle, off_msg oder prechat_msg.
Ein als String angegebener Text wird in allen Sprachen Ihres Widgets verwendet. Um nur eine Sprache zu ändern, übergeben Sie ein Objekt mit den Sprachcodes, wie im zweiten Beispiel.
Sie können den Aufruf unter dem Widget-Skript vor dem Laden oder jederzeit danach verwenden: Das Widget wird mit den neuen Texten neu gezeichnet.
onWebChat.set("texts",{
max_title: "Need help?",
max_subtitle: "We usually reply in a minute"
});
onWebChat.set("texts",{
min_online: { en: "Chat with us", es: "Chatea con nosotros" }
});
Widget-Farben setzen
Auf einer bestimmten Seite können Sie dem Kopfbereich des Widgets eine Farbe geben, solange Ihr Chat online ist, und eine andere, solange er offline ist. Verwenden Sie die Parameter onlineColor und offlineColor mit einer beliebigen CSS-Farbe, etwa "#2e7d32".
Die Farben gelten nur auf dieser Seite und ändern nicht die in Einstellungen > Widget > Widget-Einstellungen gespeicherte Farbe. Sie können sie vor dem Laden des Widgets oder jederzeit danach setzen. Die Offline-Farbe wird auch für die Senden-Schaltfläche des Offline-Formulars verwendet.
onWebChat.set("onlineColor","#2e7d32");
onWebChat.set("offlineColor","#757575");
Seiteninformationen setzen
Sie können die aktuelle Seiten-URL und den Seitentitel überschreiben, die an das onWebChat-Dashboard gemeldet werden:
Verwenden Sie den Parameter pageUrl, um eine eigene URL festzulegen. Das ist besonders nützlich für Single-Page-Apps (SPAs) oder eigenes Routing, bei dem sich die URL im Browser nicht ändert.
Verwenden Sie den Parameter pageTitle, um einen eigenen Titel festzulegen, den Agenten anstelle des Browser-Seitentitels sehen.
onWebChat.set("pageUrl","https://www.example.com/checkout/step-2");
onWebChat.set("pageTitle","Checkout: shipping details");
Widget-Status abrufen
Diese Funktion gibt "online" oder "offline" zurück, je nach Ihrer aktuellen Chat-Verfügbarkeit.
Rufen Sie dies erst auf, wenn das Widget vollständig geladen ist. Beispiel:
onWebChat.set("onWebChatLoaded", function() { console.log("chat status: " + onWebChat.get("status")); });
onWebChat.get("status");
Verbindungsstatus abrufen
Gibt true zurück, wenn das Chat-Widget eine aktive Socket-Verbindung zum Server hat, andernfalls false.
onWebChat.get("isConnected");
Öffnungszustand des Widgets abrufen
Gibt true zurück, wenn das Chat-Widget aktuell maximiert (geöffnet) ist, oder false, wenn es minimiert (geschlossen) ist.
onWebChat.get("isMaximized");
Dialog-ID abrufen
Gibt die aktuelle aktive Dialog-ID zurück oder 0, wenn kein aktiver Chat besteht. Es ist dieselbe ID wie chat_id in den Webhook-Payloads und damit nützlich für Integrationen, die eine Chat-Sitzung mit einem CRM oder Ticketsystem verknüpfen.
onWebChat.get("dialogId");
Nachricht senden
Sie können programmgesteuert eine Chat-Nachricht im Namen des Besuchers senden. Das ist nützlich für kontextbezogene Hilfeabläufe, z. B. um automatisch „Ich brauche Hilfe bei meiner Bestellung“ zu senden, wenn ein Besucher auf einen bestimmten Button klickt.
Die Nachricht erscheint im Chat genau so, als hätte der Besucher sie getippt, und das Chatfenster öffnet sich. Das Widget muss vollständig geladen und verbunden sein, bevor Sie eine Nachricht senden können. Zum Schutz vor Missbrauch sendet das Widget auf diesem Weg höchstens 3 Nachrichten pro Sekunde, 8 pro Minute und 30 pro Stunde.
onWebChat.set("sendMessage","I need help with my order");
Abteilung festlegen
Sie können eine Abteilung für den Besucher basierend auf dem Seitenkontext vorauswählen. Zum Beispiel Besucher auf Ihrer Preisseite automatisch an „Vertrieb“ und auf Ihrer Hilfeseite an „Support“ weiterleiten.
Sie können entweder den Abteilungsnamen (String) oder die Abteilungs-ID (Nummer) übergeben. Der Name muss exakt mit einer der in Ihrem Dashboard konfigurierten Abteilungen übereinstimmen.
Die Abteilungs-ID finden Sie in Ihrem Dashboard: Gehen Sie zu Einstellungen > Team > Abteilungen und klicken Sie auf eine Abteilung. Die ID wird neben dem Abteilungsnamen angezeigt.
Sie müssen die Abteilungsoption im Pre-Chat-Formular nicht aktivieren: Das Festlegen der Abteilung über die JavaScript-API funktioniert eigenständig.
Wenn kein Agent der gewählten Abteilung online ist, wird die Nachricht an alle verbundenen Agenten zugestellt. Ist der KI-Chatbot aktiviert, antwortet er nicht, solange ein Agent der Abteilung online ist, und antwortet dem Besucher, wenn niemand aus der Abteilung online ist.
Weitere Informationen zu Abteilungen finden Sie in unserem Leitfaden zu Abteilungen.
onWebChat.set("department","Sales");
onWebChat.set("department",1333);
Callback-Funktionen
Sie können Callback-Funktionen ausführen, wenn bestimmte Chat-Ereignisse eintreten:
onClick wird ausgeführt, wenn ein Besucher auf das Chat-Widget klickt.
onMaximize wird ausgeführt, wenn das Widget maximiert (geöffnet) wird.
onMinimize wird ausgeführt, wenn das Widget minimiert (geschlossen) wird.
onTrigger wird ausgeführt, wenn ein Engagement- oder Exit-Intent-Trigger ausgelöst wird, auch wenn das Widget mit show auf 0 ausgeblendet ist.
onStartWriting wird ausgeführt, wenn der Besucher beginnt, eine Nachricht zu tippen (einmal pro Browsersitzung).
onNewMessage wird ausgeführt, wenn eine neue Nachricht gesendet oder empfangen wird. Der Callback erhält zwei Argumente: den Nachrichtentext und den Absender ("visitor", "agent" oder "bot").
onEndChat wird ausgeführt, wenn der Chat endet. Der Callback erhält ein Argument, das angibt, wer ihn beendet hat ("visitor", "agent" oder "bot").
onChatStatusChange wird ausgeführt, wenn sich der Status des Chat-Widgets ändert. Der Callback erhält ein Argument mit dem neuen Status ("online" oder "offline").
onWebChatLoaded wird ausgeführt, sobald das Chat-Widget fertig geladen ist.
onWebChat.set("onClick",function(){ alert('chat widget is clicked'); });
onWebChat.set("onMaximize",function(){ alert('chat maximized'); });
onWebChat.set("onMinimize",function(){ alert('chat minimized'); });
onWebChat.set("onTrigger",function(){ alert('trigger activated'); });
onWebChat.set("onStartWriting",function(){ alert('visitor is writing'); });
onWebChat.set("onNewMessage",function(msg, by){
console.log('new message by ' + by + ': ' + msg);
});
onWebChat.set("onEndChat",function(endedBy){
console.log('chat ended by ' + endedBy);
});
onWebChat.set("onChatStatusChange",function(status){
console.log('agents are now ' + status);
});
onWebChat.set("onWebChatLoaded",function(){ alert('chat widget is loaded'); });