Live-Chat JavaScript API

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'>
        /* Paste your onWebChat widget installation snippet from the dashboard here. */
    </script>
    <script type='text/javascript'>
        /* Add your JavaScript API calls below, for example onWebChat.set() or 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. Wenn ein Sprachcode nicht aktiviert ist, wechselt das Widget zur Standardsprache. Ihre aktivierten Sprachen und die Standardsprache verwalten Sie unter Einstellungen > Sprachen.

Verfügbare Sprachcodes:

am ar az be bg bn bs ca cs da de dv dz el en es et fa fi fil fo fr he hi hr ht hu hy id is it ja ka kk kl km ko ky la lb lo lt lv mg mk mn ms mt my ne nl no pl ps pt ro ru rw si sk sl sm so sq sr sv sw tg th ti tk to tr uk ur uz vi zh zh-TW





    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 auszublenden, verwenden Sie die Funktion set mit dem Parameter show und dem Wert 0. Verwenden Sie 1, um es wieder anzuzeigen.





    onWebChat.set("max",1);

    onWebChat.set("show",0);

Widget-Größe setzen

Sie können das Widget auf einer bestimmten Seite in einer der drei Größen aus Einstellungen > Widget anzeigen, ohne die Größe im ganzen Konto zu ändern.

Verwenden Sie den Parameter size mit dem Wert "standard", "large" oder "xlarge". 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-Script 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-Script 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" }
    });

Seiteninformationen setzen

Sie können die aktuelle Seiten-URL und den Titel überschreiben, die an onWebChat gesendet werden:

Verwenden Sie den Parameter pageUrl, um eine benutzerdefinierte URL festzulegen, die den Agenten in der Chat-Konsole angezeigt wird. Dies ist nützlich für Single-Page-Apps (SPA) oder benutzerdefiniertes Routing.

Verwenden Sie den Parameter pageTitle, um einen eigenen Titel festzulegen, den Agenten anstelle des Browser-Seitentitels sehen.





    onWebChat.set("pageUrl","https://onwebchat.com/newPage");

    onWebChat.set("pageTitle","New title");

Widget-Status abrufen

Gibt "online" oder "offline" basierend auf Ihrer aktuellen Chat-Verfügbarkeit zurück.

Rufen Sie dies nach dem Laden des Widgets auf. 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, oder false andernfalls. Nützlich, um die Konnektivität vor Aktionen zu prüfen.




    onWebChat.get("isConnected");

Widget-Zustand geöffnet/geschlossen

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-Dialog vorhanden ist. Nützlich für Integrationen, die eine Chat-Sitzung mit einem CRM oder Ticketsystem verknüpfen müssen.




    onWebChat.get("dialogId");

Nachricht senden

Sie können programmatisch eine Chat-Nachricht im Namen des Besuchers senden. Nützlich für kontextbezogene Hilfeabläufe, z. B. „Ich brauche Hilfe bei meiner Bestellung“ senden, wenn ein Besucher auf einen Hilfe-Button klickt.

Die Nachricht erscheint im Chat, als hätte der Besucher sie getippt. Das Widget muss geladen und verbunden sein, bevor gesendet wird.




    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 Agents zugestellt. Außerdem antwortet der KI-Chatbot (falls aktiviert) nicht auf diesen Chat, wenn eine Abteilung über die API festgelegt wurde.

Weitere Informationen zu Abteilungen finden Sie in unserem Abteilungen-Guide.




    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 wird

onMinimize wird ausgeführt, wenn das Widget minimiert wird

onTrigger wird ausgeführt, wenn ein Trigger aktiviert wird

onStartWriting wird ausgeführt, wenn ein Besucher zu tippen beginnt

onNewMessage wird ausgeführt, wenn eine neue Nachricht gesendet oder empfangen wird. Der Callback erhält zwei Argumente: den Nachrichtentext und wer sie gesendet hat ("visitor", "agent" oder "bot")

onEndChat wird ausgeführt, wenn der Chat beendet wird. Der Callback erhält ein Argument: wer ihn beendet hat ("visitor", "agent" oder "bot")

onChatStatusChange wird ausgeführt, wenn sich der Chat-Widget-Status auf online oder offline ändert. Der Callback erhält ein Argument: den neuen Status ("online" oder "offline")

onWebChatLoaded wird ausgeführt, wenn 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'); });

Zurück zum Support