JavaScript-API: das Widget aus deiner Seite steuern

Das Widget stellt ein einziges globales Objekt bereit: window.ReactiveChat. Alle Befehle rufst du in der Funktionsform auf:

ReactiveChat('befehl', argument1, argument2);

Die Namen der Grundbefehle sind an verbreitete Chat-Widgets angelehnt (boot, shutdown, open, identify, update, track …), damit ein Umstieg wenig Arbeit macht.

Die Warteschlange vor dem Laden

Der Loader legt ReactiveChat als erstes an. Bis der Kern geladen ist, merkt sich diese Fassung jeden Aufruf in ReactiveChat.q; der Kern arbeitet die Liste danach in Reihenfolge ab. Es geht kein Aufruf verloren.

Läuft dein Code womöglich vor dem Loader-Tag, setze diese Zeile davor:

window.ReactiveChat = window.ReactiveChat || function () {
  (window.ReactiveChat.q = window.ReactiveChat.q || []).push(arguments);
};

Zwei Dinge folgen daraus:

• Vor dem Laden ist jeder Rückgabewert undefined. Befehle mit Rückgabe (getSession, isOpen, tour …) nutzt du deshalb nach dem Ereignis ready (siehe Ereignisse).
• Ein Befehl löst das Laden aus. Jeder Befehl außer boot, update, track und identify lädt den Kern sofort (Auslöser command). identify vorab ist also kostenlos.

Befehle werfen nie: ein Fehler im Befehl ergibt undefined, ein unbekannter Befehl wird ignoriert (mit data-rc-debug="true" steht er in der Konsole).

ReactiveChat('on', 'ready', function () {
  var s = ReactiveChat('getSession');
  console.log('Besucher', s && s.visitorId);
});

Start und Abbau

• boot (cfg?: object) – Der erste Aufruf setzt die Konfiguration mit denselben Feldern wie die Script-Tag-Attribute (Kamelschreibung, z. B. { siteKey, locale, theme, position, brand }) und startet. Jeder weitere Aufruf übernimmt nur noch locale, theme, dnd, autoOpen, strings und position. Fehlt boot in der Warteschlange, ruft der Kern es selbst auf.
• shutdown () – baut das Widget auf dieser Seite ab (Fenster, Verbindung, Beobachter) und setzt ReactiveChat auf eine reine Warteschlange zurück. Ein erneutes Starten ohne Neuladen der Seite ist nicht vorgesehen.

ReactiveChat('boot', { locale: 'en', theme: 'dark' });

Fenster

• open (opts?) – öffnet das Fenster. opts ist entweder ein Element (das Fenster erscheint daneben) oder ein Objekt:
• anchor (Element, optional) – neben diesem Element öffnen; ohne: normale Position.
• message (String, optional) – Text ins Eingabefeld schreiben, nicht senden (höchstens 200 Zeichen).
• tab (msg | home | help, optional) – Reiter wählen. Trägt anchor selbst data-rc-message oder data-rc-tab, gelten diese; ausdrückliche Angaben im Aufruf haben Vorrang. Vor dem Laden wird der Wunsch gemerkt.
• close () – schließt das Fenster.
• toggle () – schaltet um.
• isOpen () → boolean.

document.querySelector('#hilfe').addEventListener('click', function (ev) {
  ReactiveChat('open', { anchor: ev.currentTarget, message: 'Frage zu meiner Bestellung', tab: 'msg' });
});

Nachrichten und Gespräche

• sendMessage (text: string) – sendet eine Nachricht im Namen des Besuchers, als hätte er sie getippt (es gelten dieselben Grenzen, siehe Grenzen). Nutze das nur nach einer Handlung des Besuchers, nie ungefragt.
• newConversation () – beginnt ein neues Gespräch.
• leaveMessage () – öffnet das Formular für eine Nachricht, wenn niemand erreichbar ist.
• startConversation (text: string, suche?: string) – startet ein neues Gespräch und sendet text, sobald es bereit ist. Wird von Smart Answer benutzt, um eine Suchfrage im Chat fortzusetzen.
• continueConversation (id: string, text: string) – setzt ein bestehendes Gespräch mit text fort (id nach [0-9A-Za-z_-]{1,64}, sonst wird ein neues begonnen). Ebenfalls für die Übergabe aus Smart Answer.

Besucher und Kontext

• identify ({ userId, email, name, userHash, exp }) – meldet einen angemeldeten Nutzer. Andere Felder werden verworfen. Ohne gültigen, auf deinem Server berechneten userHash gilt der Nutzer als unbestätigt: Name und E-Mail erscheinen im Pult, aber nichts davon berechtigt zu Kundendaten oder fremden Verläufen. Alles zur Signatur unter Besucher identifizieren.
• update (attrs: object) – reicht Attribute an die MousePlayer-Anbindung weiter (nur relevant, wenn du MousePlayer einsetzt).
• track (name: string, meta?: object) – meldet einen Meilenstein. Felder in meta, die auf der Kontext-Liste stehen (url, path, title, page_type, product_id, variant_id, category, price, currency, cart_value, cart_items, in_stock u. a.), gehen als Seitenkontext an Assistent und Agenten. Andere Felder werden verworfen. Siehe Besucher identifizieren und Kontext übergeben.
• getSession () → { sessionId, visitorId, tabId } oder null.
• getEndpoint () → { siteKey, wsUrl, apiBase, locale, visitorId } – woher das Widget seine Verbindung bezieht; für eigene Skripte, die dieselbe Adresse brauchen.
• portal (basis?: string) → boolean – öffnet das Kundenportal in einem neuen Tab und übergibt dabei die bestätigte Identität. false, wenn kein bestätigter Nutzer vorliegt. basis ist optional eine eigene https://-Herkunft.

ReactiveChat('track', 'produkt_angesehen', {
  page_type: 'product', product_id: 'SKU-4711', price: 49.9, currency: 'EUR', in_stock: true
});

Sprache, Thema

• setLocale (locale: 'de' | 'en' | 'pl') – wechselt die Sprache; die Wahl wird im Browser gemerkt.
• setTheme ('light' | 'dark' | 'auto').

Teaser, Werbekarte, Touren

• showTeaser ({ text, quickReplies?, replyRoles?, avatar?, ttlMs?, ruleId? }) → boolean – zeigt eine kleine Blase am Launcher. quickReplies höchstens 3, ttlMs 0–120000 (Vorgabe 15000). Wird nicht gezeigt (false), wenn das Fenster offen ist, der Launcher ausgeblendet ist, „Nicht stören“ gilt, ein Gespräch läuft oder die Drosselung greift.
• show (text | objekt) → boolean – Kurzform: ReactiveChat('show', 'Fragen zum Versand?').
• hideTeaser / hide () – blendet die Blase aus.
• promo (false | true | objekt) – Werbekarte auf dieser Seite aus- oder wieder einblenden oder mit eigenen Feldern (titel, text, bild, knopf, ziel, link_text, link_ziel, farbe, orte, zielgruppe) überlagern.
• tour (id: string) → boolean – startet eine im Konto angelegte Produkt-Tour; false bei unbekannter Kennung. Touren richtest du unter Anpassung ein.
• tourStop () – beendet die laufende Tour.

A/B-Tests

• abVariant () → { test, variant, qa } oder null – die Variante, die dieser Besucher sieht.
• abGoal () – meldet, dass das Ziel des laufenden Tests erreicht wurde (etwa auf der Danke-Seite).

ReactiveChat('on', 'ready', function () { ReactiveChat('abGoal'); });

Gestaltung zur Laufzeit

• setBrand (marke: object) – überschreibt Farben und Form ohne Neuaufbau; null nimmt einen Wert wieder heraus.
• brandCheck () → Liste der gemessenen Kontraste { paar, ist, soll }.
• brandTokens () → die aufgelösten Gestaltungswerte.
• setStart (startseite: object) – Startseite zur Laufzeit setzen (für Vorschauen).

Die Felder dieser Objekte beschreibt Anpassung.

Ereignisse

• on (name, callback) / off (name, callback) – Ereignisse abonnieren und abbestellen. Liste und Nutzdaten: Ereignisse.

Direkt am Objekt

Nach dem Laden stehen einige Befehle auch als Methoden bereit: ReactiveChat.getSession(), ReactiveChat.isOpen(), ReactiveChat.getEndpoint(), ReactiveChat.startConversation(), ReactiveChat.continueConversation(). Dazu ReactiveChat.version (Fassung des Kerns). Vor dem Laden gibt es diese Methoden nicht – die Funktionsform ist der sichere Weg.

Was es nicht gibt

Damit niemand danach sucht: Es gibt keine Befehle destroy, reset, setUser, send, setConsent, trackPage oder navigate. Einwilligung steuerst du über deine Consent-Plattform oder data-rc-consent (Datenschutz-Einbindung), Seitenwechsel erkennt das Widget selbst (SPA), zum Abmelden siehe Besucher identifizieren.

Weiter: Ereignisse