Documentation technique

Installation

Une seule balise, à placer juste avant la fermeture de </body>. Aucune dépendance, aucune étape de compilation.

<script src="https://api.chatbot-flow.com/widget.js"
        data-api-key="cf_live_votre_cle" defer></script>

Votre clé figure dans votre espace, section Intégration. Elle est publique par nature — elle apparaît dans le code source de vos pages. Ce qui protège votre compte n'est pas son secret, mais la liste des domaines autorisés décrite plus bas.

Attributs du script

Tous se placent sur la balise <script> elle-même.

Identifier le visiteur

Quand vous savez déjà qui consulte la page — espace client, tunnel de commande — vous pouvez éviter au visiteur de ressaisir ses coordonnées. Trois écritures, par ordre de priorité décroissante :

<!-- 1. attributs, si les valeurs sont connues au rendu -->
<script src="https://api.chatbot-flow.com/widget.js"
        data-api-key="cf_live_votre_cle"
        data-user-email="client@exemple.fr"
        data-user-name="Camille Roux" defer></script>

<!-- 2. variable globale, avant le chargement du script -->
<script>
  window.ChatbotFlowUser = { email: 'client@exemple.fr', name: 'Camille Roux', phone: '' };
</script>

<!-- 3. appel dynamique, à tout moment -->
<script>ChatbotFlow('user', { email: 'client@exemple.fr', name: 'Camille Roux' });</script>

Ces coordonnées sont transmises à l'agent et enregistrées sur la conversation : vous retrouvez donc un visiteur identifié dans votre espace, sans qu'il ait eu à remplir le formulaire de contact. Une adresse invalide est ignorée plutôt que stockée, et un appel ultérieur sans identité n'efface pas ce qui était déjà connu.

Les attributs l'emportent sur window.ChatbotFlowUser. Si aucun des deux n'est présent, le widget détecte de lui-même une adresse ou un téléphone saisis dans la conversation et s'en sert pour pré-remplir le formulaire, même si l'information a été donnée plusieurs tours plus tôt.

Contexte de page

Texte libre joint à chaque message pour situer la conversation. Il n'est pas affiché au visiteur.

<script>window.ChatbotFlowPageContext = 'Fiche produit — Chaise Lina, 149 €, en stock';</script>

Ou dynamiquement, utile sur une application à navigation interne :

ChatbotFlow('pageContext', 'Étape 3 du tunnel, panier 89 €');

L'attribut data-page-context l'emporte sur la variable globale.

Langue

L'agent répond dans la langue de la page. Elle est déterminée dans cet ordre, du plus explicite au plus implicite :

1. data-lang="fr"                    sur la balise du script
2. window.ChatbotFlowLang = 'fr'     variable globale
3. <html lang="fr">                 la balise de votre page
4. la langue du navigateur du visiteur

La plupart des sites multilingues renseignent déjà <html lang> : dans ce cas il n'y a rien à ajouter au snippet, la langue suit automatiquement la page consultée. Sur une application à navigation interne, où le changement de langue ne recharge pas la page :

ChatbotFlow('lang', 'en');

Les codes acceptés sont de la forme fr ou fr-FR — la casse et le séparateur sont normalisés, pt_br devient pt-BR. Toute autre valeur est ignorée : l'agent s'en remet alors au réglage de langue de votre compte.

API JavaScript

Le script expose une fonction unique ChatbotFlow(action, données).

Ouvrir depuis votre page, avec une phrase d'introduction

Un bouton de votre site peut ouvrir la conversation et l'amorcer par une phrase de votre choix. Utile sur une fiche produit, une page tarifs ou une étape de tunnel, où la question du visiteur est prévisible.

<button onclick="ChatbotFlow('open', 'Bonjour ! Vous regardez la Chaise Lina. Que puis-je vous dire ?')">
  Poser une question sur ce produit
</button>

La phrase s'affiche comme un message de l'assistant, à la place du message d'accueil habituel. L'écriture objet est également acceptée, pour rester extensible :

ChatbotFlow('open', { intro: 'Une question sur nos tarifs ?' });

Appeler l'API avant le chargement

Le script étant différé, vos appels peuvent le précéder. Déclarez une file d'attente : les appels y sont empilés puis rejoués dès que le widget est prêt.

<script>
  window.ChatbotFlow = window.ChatbotFlow || function () {
    (window.ChatbotFlow.q = window.ChatbotFlow.q || []).push(arguments);
  };
  ChatbotFlow('user', { email: 'client@exemple.fr' });
</script>
<script async src="https://api.chatbot-flow.com/widget.js"
        data-api-key="cf_live_votre_cle"></script>

Réglages venant de votre espace

Au premier affichage, le widget interroge /api/public/config et applique votre configuration. Ces valeurs ne se règlent pas dans le code : elles se modifient depuis la page Configuration, et s'appliquent à tous vos sites sans redéploiement.

Déclencheurs

Ils décident du moment où la conversation s'ouvre d'elle-même. Ils se configurent depuis votre espace ; la colonne « valeur » indique ce que le champ attend.

Domaines autorisés

Chaque appel du widget est vérifié : l'en-tête Origin du navigateur doit figurer dans la liste des domaines déclarés sur votre page Configuration. Un domaine par ligne.

exemple.fr
www.exemple.fr
preprod.exemple.fr
localhost

Ce réglage gouverne aussi l'accès depuis le navigateur : l'en-tête Access-Control-Allow-Origin renvoyé par l'API en découle directement. Un domaine non déclaré se traduit donc par une erreur CORS dans la console, avant même que la requête ne soit examinée.

Pour intégrer le widget avant mise en ligne, déclarez localhost : le port est ignoré, une même ligne couvre donc localhost:3000 comme localhost:4200. Pensez à la retirer une fois en production.

Deux points comptent en pratique. D'abord, exemple.fr et www.exemple.fr sont deux origines distinctes : si votre site répond sur les deux, déclarez les deux, sinon le widget sera refusé sur l'une des versions. Ensuite, une liste vide désactive entièrement le contrôle — votre clé est alors acceptée depuis n'importe quel site. C'est pratique le temps d'une mise en place, mais cela laisse un tiers utiliser votre quota.

Diagnostic