JavaScript-API: de widget vanuit uw pagina aansturen

De widget biedt één globaal object: window.ReactiveChat. U roept alle opdrachten in de functievorm aan:

ReactiveChat('command', argument1, argument2);

De namen van de basisopdrachten volgen gangbare chatwidgets (boot, shutdown, open, identify, update, track …), zodat overstappen weinig werk kost.

De wachtrij vóór het laden

De loader maakt eerst ReactiveChat aan. Totdat de kern is geladen, legt deze versie elke aanroep vast in ReactiveChat.q; de kern werkt de lijst daarna op volgorde af. Geen aanroep gaat verloren.

Als uw code vóór de loadertag kan worden uitgevoerd, plaatst u deze regel ervoor:

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

Hieruit volgen twee dingen:

• Vóór het laden is elke retourwaarde undefined. Gebruik opdrachten met een retourwaarde (getSession, isOpen, tour …) daarom na de gebeurtenis ready (zie Gebeurtenissen).
• Een opdracht activeert het laden. Elke opdracht behalve boot, update, track en identify laadt de kern direct (trigger command). identify vroeg aanroepen kost daarom niets.

Opdrachten werpen nooit uitzonderingen op: een fout in een opdracht resulteert in undefined; een onbekende opdracht wordt genegeerd (met data-rc-debug="true" verschijnt deze in de console).

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

Opstarten en afsluiten

• boot (cfg?: object) – de eerste aanroep stelt de configuratie in met dezelfde velden als de scripttagattributen (camelCase, bijvoorbeeld { siteKey, locale, theme, position, brand }) en start. Elke volgende aanroep neemt alleen locale, theme, dnd, autoOpen, strings en position over. Als boot niet in de wachtrij staat, roept de kern die zelf aan.
• shutdown () – verwijdert de widget van deze pagina (venster, verbinding, observers) en zet ReactiveChat terug naar een eenvoudige wachtrij. Opnieuw starten zonder de pagina opnieuw te laden is niet de bedoeling.

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

Venster

• open (opts?) – opent het venster. opts is een element (het venster verschijnt ernaast) of een object:
• anchor (element, optioneel) – naast dit element openen; zonder: normale positie.
• message (tekenreeks, optioneel) – tekst in het invoerveld plaatsen, niet versturen (maximaal 200 tekens).
• tab (msg | home | help, optioneel) – het tabblad kiezen. Als anchor zelf data-rc-message of data-rc-tab bevat, gelden deze; expliciete waarden in de aanroep hebben voorrang. Vóór het laden wordt het verzoek onthouden.
• close () – sluit het venster.
• toggle () – schakelt het om.
• isOpen () → boolean.

document.querySelector('#hilfe').addEventListener('click', function (ev) {
  ReactiveChat('open', { anchor: ev.currentTarget, message: 'Question about my order', tab: 'msg' });
});

Berichten en gesprekken

• sendMessage (text: string) – verstuurt een bericht namens de bezoeker, alsof die het had getypt (dezelfde limieten gelden, zie Limieten). Gebruik dit alleen na een actie van de bezoeker, nooit ongevraagd.
• newConversation () – start een nieuw gesprek.
• leaveMessage () – opent het formulier om een bericht achter te laten als er niemand beschikbaar is.
• startConversation (text: string, suche?: string) – start een nieuw gesprek en verstuurt text zodra het gereed is. Gebruikt door Smart Answer om een zoekvraag in de chat voort te zetten.
• continueConversation (id: string, text: string) – zet een bestaand gesprek voort met text (id volgens [0-9A-Za-z_-]{1,64}, anders wordt een nieuw gesprek gestart). Ook gebruikt voor de overdracht vanuit Smart Answer.

Bezoekers en context

• identify ({ userId, email, name, userHash, exp }) – meldt een ingelogde gebruiker. Andere velden worden verworpen. Zonder geldige userHash die op uw server is berekend, geldt de gebruiker als onbevestigd: naam en e-mail verschijnen in het paneel, maar geven geen toegang tot klantgegevens of gespreksgeschiedenissen van anderen. Alles over de handtekening staat onder Bezoekers identificeren.
• update (attrs: object) – geeft attributen door aan de MousePlayer-koppeling (alleen relevant als u MousePlayer gebruikt).
• track (name: string, meta?: object) – meldt een mijlpaal. Velden in meta die op de contextlijst staan (url, path, title, page_type, product_id, variant_id, category, price, currency, cart_value, cart_items, in_stock en andere), gaan als paginacontext naar de assistent en medewerkers. Andere velden worden verworpen. Zie Bezoekers identificeren en context doorgeven.
• getSession () → { sessionId, visitorId, tabId } of null.
• getEndpoint () → { siteKey, wsUrl, apiBase, locale, visitorId } – waar de widget de verbinding vandaan haalt; voor uw eigen scripts die hetzelfde adres nodig hebben.
• portal (basis?: string) → boolean – opent het klantenportaal in een nieuw tabblad en geeft de bevestigde identiteit door. false als er geen bevestigde gebruiker is. basis is een optionele eigen https:// origin.

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

Taal, thema

• setLocale (locale: 'de' | 'en' | 'pl') – schakelt de taal om; de keuze wordt in de browser onthouden.
• setTheme ('light' | 'dark' | 'auto').

Tooltipballon, promotiekaart, tours

• showTeaser ({ text, quickReplies?, replyRoles?, avatar?, ttlMs?, ruleId? }) → boolean – toont een kleine ballon bij de chatknop. quickReplies maximaal 3, ttlMs 0–120000 (standaard 15000). Deze wordt niet getoond (false) als het venster open is, de chatknop verborgen is, ‘Niet storen’ geldt, er een gesprek loopt of een frequentiebeperking geldt.
• show (text | object) → boolean – verkorte vorm: ReactiveChat('show', 'Questions about shipping?').
• hideTeaser / hide () – verbergt de ballon.
• promo (false | true | object) – de promotiekaart op deze pagina verbergen, weer tonen of met uw eigen velden overschrijven (titel, text, bild, knopf, ziel, link_text, link_ziel, farbe, orte, zielgruppe).
• tour (id: string) → boolean – start een producttour die in uw account is gemaakt; false bij een onbekende ID. Tours stelt u in onder Aanpassen.
• tourStop () – beëindigt de lopende tour.

A/B-tests

• abVariant () → { test, variant, qa } of null – de variant die deze bezoeker ziet.
• abGoal () – meldt dat het doel van de lopende test is bereikt (bijvoorbeeld op de bedankpagina).

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

Ontwerp tijdens de uitvoering

• setBrand (marke: object) – overschrijft kleuren en vorm zonder opnieuw te bouwen; null verwijdert een waarde weer.
• brandCheck () → lijst met gemeten contrasten { paar, ist, soll }.
• brandTokens () → de berekende ontwerpwaarden.
• setStart (startseite: object) – het startscherm tijdens de uitvoering instellen (voor voorbeelden).

De velden van deze objecten staan beschreven onder Aanpassen.

Gebeurtenissen

• on (name, callback) / off (name, callback) – op gebeurtenissen abonneren en afmelden. Lijst en gegevens: Gebeurtenissen.

Rechtstreeks op het object

Na het laden zijn sommige opdrachten ook als methoden beschikbaar: ReactiveChat.getSession(), ReactiveChat.isOpen(), ReactiveChat.getEndpoint(), ReactiveChat.startConversation(), ReactiveChat.continueConversation(). Daarnaast ReactiveChat.version (versie van de kern). Deze methoden bestaan niet vóór het laden — de functievorm is de veilige manier.

Wat er niet is

Zodat niemand ernaar zoekt: er zijn geen opdrachten destroy, reset, setUser, send, setConsent, trackPage of navigate. U regelt toestemming via uw toestemmingsplatform of data-rc-consent (Privacy-integratie), de widget herkent paginawijzigingen zelf (SPA) en voor uitloggen zie Bezoekers identificeren.

Volgende: Gebeurtenissen