JavaScript API: controlling the widget from your page

The widget provides a single global object: window.ReactiveChat. You call all commands in the function form:

ReactiveChat('command', argument1, argument2);

The names of the basic commands follow common chat widgets (boot, shutdown, open, identify, update, track …), so that switching over takes little work.

The queue before loading

The loader creates ReactiveChat first. Until the core has loaded, this version records every call in ReactiveChat.q; the core then works through the list in order. No call is lost.

If your code might run before the loader tag, put this line in front of it:

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

Two things follow from this:

• Before loading, every return value is undefined. So use commands with a return value (getSession, isOpen, tour …) after the ready event (see Events).
• A command triggers loading. Every command except boot, update, track and identify loads the core immediately (trigger command). Calling identify early therefore costs nothing.

Commands never throw: an error in a command results in undefined, an unknown command is ignored (with data-rc-debug="true" it appears in the console).

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

Start-up and shutdown

• boot (cfg?: object) – the first call sets the configuration with the same fields as the script tag attributes (camel case, e.g. { siteKey, locale, theme, position, brand }) and starts. Every further call only takes over locale, theme, dnd, autoOpen, strings and position. If boot is missing from the queue, the core calls it itself.
• shutdown () – removes the widget from this page (window, connection, observers) and resets ReactiveChat to a plain queue. Starting again without reloading the page is not intended.

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

Window

• open (opts?) – opens the window. opts is either an element (the window appears next to it) or an object:
• anchor (element, optional) – open next to this element; without it: normal position.
• message (string, optional) – write text into the input field, not send it (at most 200 characters).
• tab (msg | home | help, optional) – choose the tab. If anchor itself carries data-rc-message or data-rc-tab, these apply; explicit values in the call take precedence. Before loading, the request is remembered.
• close () – closes the window.
• toggle () – toggles it.
• isOpen () → boolean.

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

Messages and conversations

• sendMessage (text: string) – sends a message on behalf of the visitor, as if they had typed it (the same limits apply, see Limits). Only use this after an action by the visitor, never unprompted.
• newConversation () – starts a new conversation.
• leaveMessage () – opens the form for leaving a message when nobody is available.
• startConversation (text: string, suche?: string) – starts a new conversation and sends text as soon as it is ready. Used by Smart Answer to continue a search question in the chat.
• continueConversation (id: string, text: string) – continues an existing conversation with text (id matching [0-9A-Za-z_-]{1,64}, otherwise a new one is started). Also used for the handover from Smart Answer.

Visitors and context

• identify ({ userId, email, name, userHash, exp }) – reports a signed-in user. Other fields are discarded. Without a valid userHash computed on your server, the user counts as unconfirmed: name and email appear in the desk, but none of it grants access to customer data or other people's conversation histories. Everything about the signature is under Identifying visitors.
• update (attrs: object) – passes attributes on to the MousePlayer connection (only relevant if you use MousePlayer).
• track (name: string, meta?: object) – reports a milestone. Fields in meta that are on the context list (url, path, title, page_type, product_id, variant_id, category, price, currency, cart_value, cart_items, in_stock and others) go to the assistant and agents as page context. Other fields are discarded. See Identifying visitors and passing context.
• getSession () → { sessionId, visitorId, tabId } or null.
• getEndpoint () → { siteKey, wsUrl, apiBase, locale, visitorId } – where the widget gets its connection from; for your own scripts that need the same address.
• portal (basis?: string) → boolean – opens the customer portal in a new tab and passes on the confirmed identity. false if there is no confirmed user. basis is an optional https:// origin of your own.

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

Language, theme

• setLocale (locale: 'de' | 'en' | 'pl') – switches the language; the choice is remembered in the browser.
• setTheme ('light' | 'dark' | 'auto').

Teaser, promo card, tours

• showTeaser ({ text, quickReplies?, replyRoles?, avatar?, ttlMs?, ruleId? }) → boolean – shows a small bubble at the launcher. quickReplies at most 3, ttlMs 0–120000 (default 15000). It is not shown (false) if the window is open, the launcher is hidden, “Do not disturb” applies, a conversation is in progress or throttling applies.
• show (text | object) → boolean – short form: ReactiveChat('show', 'Questions about shipping?').
• hideTeaser / hide () – hides the bubble.
• promo (false | true | object) – hide the promo card on this page, show it again, or override it with your own fields (titel, text, bild, knopf, ziel, link_text, link_ziel, farbe, orte, zielgruppe).
• tour (id: string) → boolean – starts a product tour created in your account; false for an unknown ID. Tours are set up under Customisation.
• tourStop () – ends the running tour.

A/B tests

• abVariant () → { test, variant, qa } or null – the variant this visitor sees.
• abGoal () – reports that the goal of the running test has been reached (for example on the thank-you page).

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

Design at runtime

• setBrand (marke: object) – overrides colours and shape without a rebuild; null removes a value again.
• brandCheck () → list of the measured contrasts { paar, ist, soll }.
• brandTokens () → the resolved design values.
• setStart (startseite: object) – set the start screen at runtime (for previews).

The fields of these objects are described under Customisation.

Events

• on (name, callback) / off (name, callback) – subscribe to and unsubscribe from events. List and payloads: Events.

Directly on the object

Once loaded, some commands are also available as methods: ReactiveChat.getSession(), ReactiveChat.isOpen(), ReactiveChat.getEndpoint(), ReactiveChat.startConversation(), ReactiveChat.continueConversation(). In addition, ReactiveChat.version (version of the core). These methods do not exist before loading – the function form is the safe way.

What does not exist

So that nobody goes looking: there are no commands destroy, reset, setUser, send, setConsent, trackPage or navigate. You control consent through your consent platform or data-rc-consent (Privacy integration), the widget detects page changes by itself (SPA), and for signing out see Identifying visitors.

Next: Events