API JavaScript : contrôler le widget depuis votre page

Le widget fournit un seul objet global : window.ReactiveChat. Vous appelez toutes les commandes sous forme de fonction :

ReactiveChat('command', argument1, argument2);

Les noms des commandes de base suivent ceux des widgets de chat courants (boot, shutdown, open, identify, update, track…), afin de faciliter la migration.

La file de commandes avant le chargement

Le chargeur crée d’abord ReactiveChat. Tant que le noyau n’est pas chargé, cette version consigne chaque appel dans ReactiveChat.q ; le noyau parcourt ensuite la liste dans l’ordre. Aucun appel n’est perdu.

Si votre code risque de s’exécuter avant la balise du chargeur, placez cette ligne devant :

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

Deux conséquences :

• Avant le chargement, chaque valeur de retour est undefined. Utilisez donc les commandes avec valeur de retour (getSession, isOpen, tour…) après l’événement ready (voir Événements).
• Une commande déclenche le chargement. Toute commande sauf boot, update, track et identify charge immédiatement le noyau (déclencheur command). Appeler identify tôt ne coûte donc rien.

Les commandes ne lèvent jamais d’exception : une erreur de commande produit undefined, une commande inconnue est ignorée (avec data-rc-debug="true", elle apparaît dans la console).

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

Démarrage et arrêt

• boot (cfg?: object) – le premier appel définit la configuration avec les mêmes champs que les attributs de la balise script (camelCase, par ex. { siteKey, locale, theme, position, brand }) et démarre. Chaque appel suivant ne reprend que locale, theme, dnd, autoOpen, strings et position. Si boot manque dans la file, le noyau l’appelle lui-même.
• shutdown () – retire le widget de cette page (fenêtre, connexion, observateurs) et remet ReactiveChat sous forme de simple file de commandes. Un redémarrage sans rechargement de la page n’est pas prévu.

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

Fenêtre

• open (opts?) – ouvre la fenêtre. opts est soit un élément (la fenêtre apparaît à côté), soit un objet :
• anchor (élément, facultatif) – ouvrir à côté de cet élément ; sans lui, position habituelle.
• message (chaîne, facultatif) – écrire du texte dans le champ de saisie, sans l’envoyer (200 caractères maximum).
• tab (msg | home | help, facultatif) – choisir l’onglet. Si anchor porte lui-même data-rc-message ou data-rc-tab, ces attributs s’appliquent ; les valeurs explicites de l’appel sont prioritaires. Avant le chargement, la demande est mémorisée.
• close () – ferme la fenêtre.
• toggle () – ouvre ou ferme la fenêtre.
• isOpen () → boolean.

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

Messages et conversations

• sendMessage (text: string) – envoie un message au nom du visiteur, comme s’il l’avait saisi (mêmes limites, voir Limites). Utilisez cette commande uniquement après une action du visiteur, jamais sans sollicitation.
• newConversation () – démarre une nouvelle conversation.
• leaveMessage () – ouvre le formulaire pour laisser un message lorsque personne n’est disponible.
• startConversation (text: string, suche?: string) – démarre une nouvelle conversation et envoie text dès qu’elle est prête. Utilisé par Smart Answer pour poursuivre une question de recherche dans le chat.
• continueConversation (id: string, text: string) – poursuit une conversation existante avec text (id conforme à [0-9A-Za-z_-]{1,64}, sinon une nouvelle conversation est créée). Également utilisé pour le transfert depuis Smart Answer.

Visiteurs et contexte

• identify ({ userId, email, name, userHash, exp }) – signale un utilisateur connecté. Les autres champs sont écartés. Sans userHash valide calculé sur votre serveur, l’utilisateur est considéré comme non confirmé : nom et e-mail apparaissent dans l’espace agents, mais ne donnent aucun accès aux données clients ou aux historiques des autres personnes. Tous les détails de la signature figurent dans Identifier les visiteurs.
• update (attrs: object) – transmet des attributs à la connexion MousePlayer (uniquement pertinent si vous utilisez MousePlayer).
• track (name: string, meta?: object) – signale une étape. Les champs de meta présents dans la liste de contexte (url, path, title, page_type, product_id, variant_id, category, price, currency, cart_value, cart_items, in_stock et autres) sont transmis à l’assistant et aux agents comme contexte de page. Les autres champs sont écartés. Voir Identifier les visiteurs et transmettre du contexte.
• getSession () → { sessionId, visitorId, tabId } ou null.
• getEndpoint () → { siteKey, wsUrl, apiBase, locale, visitorId } – d’où le widget tire sa connexion ; pour vos scripts ayant besoin de la même adresse.
• portal (basis?: string) → boolean – ouvre le portail client dans un nouvel onglet et transmet l’identité confirmée. false sans utilisateur confirmé. basis est votre propre origine https:// facultative.

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

Langue, thème

• setLocale (locale: 'de' | 'en' | 'pl') – change la langue ; le choix est mémorisé dans le navigateur.
• setTheme ('light' | 'dark' | 'auto').

Bulles de relance, carte promotionnelle, visites

• showTeaser ({ text, quickReplies?, replyRoles?, avatar?, ttlMs?, ruleId? }) → boolean – affiche une petite bulle près du bouton du chat. quickReplies : 3 maximum, ttlMs : 0–120000 (15000 par défaut). Elle n’est pas affichée (false) si la fenêtre est ouverte, le bouton du chat masqué, « Ne pas déranger » actif, une conversation en cours ou une limitation applicable.
• show (text | object) → boolean – forme courte : ReactiveChat('show', 'Questions about shipping?').
• hideTeaser / hide () – masque la bulle.
• promo (false | true | object) – masquer la carte promotionnelle sur cette page, la réafficher ou la remplacer avec vos champs (titel, text, bild, knopf, ziel, link_text, link_ziel, farbe, orte, zielgruppe).
• tour (id: string) → boolean – démarre une visite guidée créée dans votre compte ; false pour un identifiant inconnu. Les visites se configurent sous Personnalisation.
• tourStop () – termine la visite en cours.

Tests A/B

• abVariant () → { test, variant, qa } ou null – la variante vue par ce visiteur.
• abGoal () – signale que l’objectif du test en cours est atteint (par exemple sur la page de remerciement).

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

Design à l’exécution

• setBrand (marke: object) – remplace les couleurs et la forme sans reconstruction ; null retire à nouveau une valeur.
• brandCheck () → liste des contrastes mesurés { paar, ist, soll }.
• brandTokens () → les valeurs de design résolues.
• setStart (startseite: object) – définit l’écran d’accueil à l’exécution (pour les aperçus).

Les champs de ces objets sont décrits sous Personnalisation.

Événements

• on (name, callback) / off (name, callback) – s’abonner aux événements et s’en désabonner. Liste et données : Événements.

Directement sur l’objet

Après le chargement, certaines commandes sont aussi disponibles comme méthodes : ReactiveChat.getSession(), ReactiveChat.isOpen(), ReactiveChat.getEndpoint(), ReactiveChat.startConversation(), ReactiveChat.continueConversation(). S’y ajoute ReactiveChat.version (version du noyau). Ces méthodes n’existent pas avant le chargement ; la forme de fonction est la voie sûre.

Ce qui n’existe pas

Pour éviter de chercher : aucune commande destroy, reset, setUser, send, setConsent, trackPage ou navigate n’existe. Vous contrôlez le consentement via votre plateforme ou data-rc-consent (Intégration de la confidentialité), le widget détecte lui-même les changements de page (SPA) et la déconnexion est décrite dans Identifier les visiteurs.

Suite : Événements