FlowHunt JS API : Guide d'intégration pour utilisateurs avancés

Référence complète pour l’intégration de FlowHunt JS API v2. Apprenez à intégrer le chatbot, vous abonner aux 10 événements, utiliser les variables de flux, suivre les interactions avec les paramètres URL et contrôler la fenêtre de chat par programmation.

FlowHunt JavaScript API Chatbot Integration

La FlowHunt JS API vous donne un contrôle total sur la façon dont votre chatbot s’intègre à votre site web. En utilisant le code d’intégration v2, vous pouvez intégrer le chatbot, vous abonner aux événements de cycle de vie et d’interaction, transmettre des données dynamiques via des variables de flux, suivre les interactions avec des paramètres URL et contrôler la fenêtre de chat par programmation.

Ce guide couvre tous les aspects de la JS API avec des exemples de code que vous pouvez copier et adapter à votre projet.

Code d’intégration (v2)

Lorsque vous créez un chatbot dans FlowHunt, vous obtenez un extrait de code d’intégration. Copiez-le et collez-le dans votre HTML juste avant la balise fermante </body> :

<script id="fh-chatbot-script-YOUR_CHATBOT_ID">
  var currentScript = document.currentScript
    || document.getElementById('fh-chatbot-script-YOUR_CHATBOT_ID');

  var script = document.createElement('script');
  script.async = true;
  script.src = 'https://app.flowhunt.io/api/chatbot/YOUR_CHATBOT_ID'
    + '?workspace_id=YOUR_WORKSPACE_ID&v=2';

  script.onload = function() {
    window.FHChatbot_YOUR_CHATBOT_ID.init(function(chatbotManager) {
      // The chatbot is ready — use chatbotManager here
    });
  };

  if (currentScript && currentScript.parentNode) {
    currentScript.parentNode.insertBefore(script, currentScript.nextSibling);
  } else {
    document.head.appendChild(script);
  }
</script>

Remplacez YOUR_CHATBOT_ID et YOUR_WORKSPACE_ID par les valeurs de votre tableau de bord FlowHunt. L’ID du chatbot dans le nom de la variable globale (window.FHChatbot_YOUR_CHATBOT_ID) utilise des underscores au lieu de tirets.

Remplacer la configuration avec setConfig()

Avant d’appeler init(), vous pouvez remplacer les paramètres par défaut du chatbot en utilisant setConfig() :

<script id="fh-chatbot-script-YOUR_CHATBOT_ID">
  var currentScript = document.currentScript
    || document.getElementById('fh-chatbot-script-YOUR_CHATBOT_ID');

  var script = document.createElement('script');
  script.async = true;
  script.src = 'https://app.flowhunt.io/api/chatbot/YOUR_CHATBOT_ID'
    + '?workspace_id=YOUR_WORKSPACE_ID&v=2';

  script.onload = function() {
    window.FHChatbot_YOUR_CHATBOT_ID.setConfig({
      headerTitle: 'Support Assistant',
      maxWindowWidth: '700px',
      showChatButton: false,
      flowVariables: {
        userId: '12345',
        plan: 'enterprise'
      },
      urlSuffix: '?utm_source=chatbot'
    });

    window.FHChatbot_YOUR_CHATBOT_ID.init(function(chatbotManager) {
      // Chatbot initialized with custom config
    });
  };

  if (currentScript && currentScript.parentNode) {
    currentScript.parentNode.insertBefore(script, currentScript.nextSibling);
  } else {
    document.head.appendChild(script);
  }
</script>

Options de configuration disponibles

OptionTypeDescription
headerTitlestringTexte personnalisé du titre de l’en-tête
maxWindowWidthstringLargeur maximale de la fenêtre de chat (par exemple, '700px')
maxWindowHeightstringHauteur maximale de la fenêtre de chat
inputPlaceholderstringTexte d’espace réservé pour le champ de saisie des messages
showChatButtonbooleanAfficher ou masquer le bouton de chat flottant par défaut
openChatPanelbooleanOuvrir automatiquement le panneau de chat au chargement de la page
flowVariablesobjectPaires clé-valeur de données personnalisées transmises au flux
urlSuffixstringChaîne de requête ajoutée à toutes les URL générées par le chatbot
cookieConsentbooleanActiver la persistance de session via les cookies
embeddedstringActiver le mode intégré (pas de bouton de fermeture)
themestringMode de thème
Logo

Prêt à développer votre entreprise?

Commencez votre essai gratuit aujourd'hui et voyez les résultats en quelques jours.

Demander une démo Se connecter

Variables de flux : Transmettre des données dynamiques

Les variables de flux vous permettent d’envoyer des données personnalisées depuis votre site web vers le flux du chatbot. Cela permet des conversations personnalisées en fonction du contexte utilisateur.

window.FHChatbot_YOUR_CHATBOT_ID.setConfig({
  flowVariables: {
    userId: getCurrentUserId(),
    userEmail: getCurrentUserEmail(),
    currentPage: window.location.pathname,
    plan: 'enterprise'
  }
});

Une fois définies, ces variables sont accessibles dans la logique du flux de votre chatbot, vous permettant de personnaliser les réponses, d’orienter les conversations ou de transmettre du contexte aux agents IA.

Suffixe URL : Suivre les interactions du chatbot

Le paramètre urlSuffix ajoute une chaîne de requête à chaque URL générée par le chatbot. Ceci est utile pour suivre le trafic provenant du chatbot dans les outils d’analyse :

window.FHChatbot_YOUR_CHATBOT_ID.setConfig({
  urlSuffix: '?utm_source=chatbot&utm_medium=widget'
});

Cas d’utilisation :

  • Suivre les conversions des interactions du chatbot dans Google Analytics.
  • Analyser le comportement des utilisateurs après leur engagement avec le chatbot.
  • Attribuer les campagnes qui stimulent l’engagement du chatbot.

Référence des événements

La FlowHunt JS API envoie 10 événements personnalisés sur l’objet window. Tous les événements utilisent l’API CustomEvent avec bubbles: true et composed: true.

onFHChatbotReady

Déclenché lorsque le widget du chatbot est entièrement rendu et prêt à être utilisé.

  • Données de l’événement : Aucune
  • Quand : Après que le DOM du widget est monté et le bouton de chat est visible.

onFHChatbotSessionCreated

Déclenché lorsqu’une nouvelle session de chat est créée sur le serveur. Se déclenche également lors du redémarrage de la session.

  • Données de l’événement : Aucune
  • Quand : Après un appel API réussi de création de session.

onFHChatbotWindowOpened

Déclenché lorsque l’utilisateur ouvre la fenêtre de chat.

  • Données de l’événement : Aucune
  • Quand : Le panneau de chat devient visible.
  • Note : Non déclenché en mode intégré.

onFHChatbotWindowClosed

Déclenché lorsque l’utilisateur ferme la fenêtre de chat.

  • Données de l’événement : Aucune
  • Quand : Le panneau de chat est masqué.
  • Note : Non déclenché en mode intégré.

onFHMessageSent

Déclenché lorsque l’utilisateur envoie un message.

  • Données de l’événement (event.detail.metadata) :
{
  "content": "Hello, I need help with...",
  "createdAt": "2026-02-19T10:30:00.000Z"
}

onFHMessageReceived

Déclenché lorsque le chatbot reçoit et affiche une réponse.

  • Données de l’événement (event.detail.metadata) :
{
  "flow_id": "abc123",
  "message_id": "msg_456",
  "message": "Sure, I can help you with that!",
  "sender": {
    "sender_name": "Support Agent",
    "sender_avatar": "https://example.com/avatar.png"
  }
}

Le champ sender est optionnel et n’est présent que lorsqu’un agent humain est impliqué.

onFHFormDataSent

Déclenché lorsque l’utilisateur soumet des données de formulaire via le chatbot.

  • Données de l’événement (event.detail.metadata) :
{
  "objectData": { "name": "John", "email": "john@example.com" },
  "createdAt": "2026-02-19T10:31:00.000Z"
}

onFHFeedback

Déclenché lorsqu’un utilisateur donne un avis positif ou négatif sur un message du chatbot.

  • Données de l’événement (event.detail.metadata) :
{
  "message_id": "msg_456",
  "content": "Optional feedback text",
  "feedback": "P"
}

La valeur de feedback est "P" pour positif (pouce en haut) ou "N" pour négatif (pouce en bas).

onFHToolCall

Déclenché lorsqu’un outil ou une action est exécuté pendant le traitement du flux.

  • Données de l’événement (event.detail.metadata) :
{
  "metadata": {
    "flow_id": "abc123",
    "message_id": "msg_789",
    "message": "Calling search API..."
  },
  "createdAt": "2026-02-19T10:32:00.000Z"
}

Note : Déclenché uniquement dans les modes flowAssistant et flowAssistantV3, pas en mode chatbot standard.

onFHError

Déclenché lorsqu’une erreur survient pendant le fonctionnement du chatbot.

  • Données de l’événement (event.detail.metadata) :
{
  "metadata": {
    "flow_id": "abc123",
    "message_id": "msg_err",
    "message": "Flow execution failed"
  },
  "createdAt": "2026-02-19T10:33:00.000Z"
}

S’abonner aux événements

Il existe deux façons de s’abonner aux événements du chatbot.

Méthode 1 : Écouteurs d’événements Window

Utilisez window.addEventListener n’importe où dans votre page. Cela fonctionne même avant le chargement du chatbot :

<script>
document.addEventListener('DOMContentLoaded', function() {
  // Chatbot lifecycle events
  window.addEventListener('onFHChatbotReady', function(event) {
    console.log('Chatbot is ready');
  });

  window.addEventListener('onFHChatbotSessionCreated', function(event) {
    console.log('Session created');
  });

  window.addEventListener('onFHChatbotWindowOpened', function(event) {
    console.log('Chat window opened');
  });

  window.addEventListener('onFHChatbotWindowClosed', function(event) {
    console.log('Chat window closed');
  });

  // Message events
  window.addEventListener('onFHMessageSent', function(event) {
    console.log('User sent:', event.detail.metadata.content);
  });

  window.addEventListener('onFHMessageReceived', function(event) {
    console.log('Bot replied:', event.detail.metadata.message);
  });

  window.addEventListener('onFHFormDataSent', function(event) {
    console.log('Form submitted:', event.detail.metadata.objectData);
  });

  // Feedback
  window.addEventListener('onFHFeedback', function(event) {
    var feedback = event.detail.metadata;
    console.log('Feedback on message', feedback.message_id, ':',
      feedback.feedback);
  });

  // Tool calls (flowAssistant modes only)
  window.addEventListener('onFHToolCall', function(event) {
    console.log('Tool called:', event.detail.metadata);
  });

  // Errors
  window.addEventListener('onFHError', function(event) {
    console.error('Chatbot error:', event.detail.metadata);
  });
});
</script>

Pour cesser d’écouter un événement, utilisez removeEventListener avec la même référence de fonction :

var handleMessage = function(event) {
  console.log(event.detail.metadata);
};
window.addEventListener('onFHMessageReceived', handleMessage);

// Later, when you want to stop listening:
window.removeEventListener('onFHMessageReceived', handleMessage);

Méthode 2 : Méthodes de callback du gestionnaire

À l’intérieur du callback init(), utilisez les méthodes intégrées du gestionnaire de chatbot :

window.FHChatbot_YOUR_CHATBOT_ID.init(function(chatbotManager) {
  chatbotManager.onSessionCreated(function() {
    console.log('Session created');
  });

  chatbotManager.onWindowOpened(function() {
    console.log('Window opened');
  });

  chatbotManager.onWindowClosed(function() {
    console.log('Window closed');
  });

  chatbotManager.onMessageSent(function(event) {
    console.log('User sent:', event.metadata);
  });

  chatbotManager.onMessageReceived(function(event) {
    console.log('Bot replied:', event.metadata);
  });

  chatbotManager.onFormDataSent(function(event) {
    console.log('Form data:', event.metadata);
  });

  chatbotManager.onFeedback(function(event) {
    console.log('Feedback:', event.metadata);
  });

  chatbotManager.onToolCall(function(event) {
    console.log('Tool call:', event.metadata);
  });

  chatbotManager.onError(function(event) {
    console.error('Error:', event.metadata);
  });
});

Référence des méthodes du gestionnaire

MethodParametersDescription
onSessionCreated(fn)fn: () => voidÉcouter la création de session
onWindowOpened(fn)fn: () => voidÉcouter l’ouverture de la fenêtre
onWindowClosed(fn)fn: () => voidÉcouter la fermeture de la fenêtre
onMessageSent(fn)fn: (event) => voidÉcouter les messages de l’utilisateur
onMessageReceived(fn)fn: (event) => voidÉcouter les réponses du bot
onFormDataSent(fn)fn: (event) => voidÉcouter les soumissions de formulaires
onFeedback(fn)fn: (event) => voidÉcouter les retours de l’utilisateur
onToolCall(fn)fn: (event) => voidÉcouter les exécutions d’outils
onError(fn)fn: (event) => voidÉcouter les erreurs
openChat()—Ouvre le panneau de chat
closeChat()—Ferme le panneau de chat

Activation personnalisée du chat : Masquer le bouton et ouvrir au clic

Pour contrôler entièrement quand le chatbot apparaît, masquez le bouton flottant par défaut et ouvrez le chat par programmation — par exemple, depuis votre propre bouton personnalisé.

Exemple complet

<!-- Your custom chat button -->
<button id="my-chat-button">Chat with us</button>

<!-- FlowHunt integration with hidden default button -->
<script id="fh-chatbot-script-YOUR_CHATBOT_ID">
  var currentScript = document.currentScript
    || document.getElementById('fh-chatbot-script-YOUR_CHATBOT_ID');

  var script = document.createElement('script');
  script.async = true;
  script.src = 'https://app.flowhunt.io/api/chatbot/YOUR_CHATBOT_ID'
    + '?workspace_id=YOUR_WORKSPACE_ID&v=2';

  script.onload = function() {
    window.FHChatbot_YOUR_CHATBOT_ID.setConfig({
      showChatButton: false
    });

    window.FHChatbot_YOUR_CHATBOT_ID.init(function(chatbotManager) {
      // Open chat when your custom button is clicked
      document.getElementById('my-chat-button')
        .addEventListener('click', function() {
          chatbotManager.openChat();
        });
    });
  };

  if (currentScript && currentScript.parentNode) {
    currentScript.parentNode.insertBefore(script, currentScript.nextSibling);
  } else {
    document.head.appendChild(script);
  }
</script>

Afficher un bouton personnalisé uniquement lorsque le chatbot est prêt

Vous pouvez combiner l’activation masquée avec des écouteurs d’événements pour créer des interactions avancées :

<button id="open-chat" style="display:none;">Need help?</button>

<script>
// Show a custom button only when the chatbot is ready
window.addEventListener('onFHChatbotReady', function() {
  document.getElementById('open-chat').style.display = 'block';
});
</script>

<!-- FlowHunt integration -->
<script id="fh-chatbot-script-YOUR_CHATBOT_ID">
  var currentScript = document.currentScript
    || document.getElementById('fh-chatbot-script-YOUR_CHATBOT_ID');

  var script = document.createElement('script');
  script.async = true;
  script.src = 'https://app.flowhunt.io/api/chatbot/YOUR_CHATBOT_ID'
    + '?workspace_id=YOUR_WORKSPACE_ID&v=2';

  script.onload = function() {
    window.FHChatbot_YOUR_CHATBOT_ID.setConfig({
      showChatButton: false
    });

    window.FHChatbot_YOUR_CHATBOT_ID.init(function(chatbotManager) {
      document.getElementById('open-chat')
        .addEventListener('click', function() {
          chatbotManager.openChat();
        });
    });
  };

  if (currentScript && currentScript.parentNode) {
    currentScript.parentNode.insertBefore(script, currentScript.nextSibling);
  } else {
    document.head.appendChild(script);
  }
</script>

Exemple d’intégration complet

Un exemple fonctionnel complet qui démontre les remplacements de configuration, le suivi des événements et l’activation personnalisée du chat ensemble :

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>FlowHunt Chatbot Integration</title>
</head>
<body>
  <h1>My Website</h1>
  <button id="open-chat-btn">Talk to our AI assistant</button>
  <button id="close-chat-btn">Close chat</button>

  <!-- Subscribe to events before the chatbot loads -->
  <script>
  document.addEventListener('DOMContentLoaded', function() {
    window.addEventListener('onFHChatbotReady', function() {
      console.log('Chatbot widget is ready');
    });

    window.addEventListener('onFHChatbotSessionCreated', function() {
      console.log('New chat session started');
    });

    window.addEventListener('onFHMessageSent', function(event) {
      console.log('User message:', event.detail.metadata.content);
    });

    window.addEventListener('onFHMessageReceived', function(event) {
      console.log('Bot response:', event.detail.metadata.message);
    });

    window.addEventListener('onFHFeedback', function(event) {
      var fb = event.detail.metadata;
      if (fb.feedback === 'P') {
        console.log('Positive feedback on message', fb.message_id);
      } else {
        console.log('Negative feedback on message', fb.message_id);
      }
    });

    window.addEventListener('onFHError', function(event) {
      console.error('Chatbot error:', event.detail.metadata);
    });
  });
  </script>

  <!-- FlowHunt integration -->
  <script id="fh-chatbot-script-YOUR_CHATBOT_ID">
    var currentScript = document.currentScript
      || document.getElementById('fh-chatbot-script-YOUR_CHATBOT_ID');

    var script = document.createElement('script');
    script.async = true;
    script.src = 'https://app.flowhunt.io/api/chatbot/YOUR_CHATBOT_ID'
      + '?workspace_id=YOUR_WORKSPACE_ID&v=2';

    script.onload = function() {
      window.FHChatbot_YOUR_CHATBOT_ID.setConfig({
        showChatButton: false,
        headerTitle: 'AI Assistant',
        maxWindowWidth: '600px',
        flowVariables: {
          source: 'website',
          page: window.location.pathname
        },
        urlSuffix: '?utm_source=chatbot'
      });

      window.FHChatbot_YOUR_CHATBOT_ID.init(function(chatbotManager) {
        document.getElementById('open-chat-btn')
          .addEventListener('click', function() {
            chatbotManager.openChat();
          });

        document.getElementById('close-chat-btn')
          .addEventListener('click', function() {
            chatbotManager.closeChat();
          });
      });
    };

    if (currentScript && currentScript.parentNode) {
      currentScript.parentNode.insertBefore(script, currentScript.nextSibling);
    } else {
      document.head.appendChild(script);
    }
  </script>
</body>
</html>

Questions fréquemment posées

Quels événements puis-je écouter avec la FlowHunt JS API ?

La FlowHunt JS API émet 10 événements : onFHChatbotReady, onFHChatbotSessionCreated, onFHChatbotWindowOpened, onFHChatbotWindowClosed, onFHMessageSent, onFHMessageReceived, onFHFormDataSent, onFHFeedback, onFHToolCall et onFHError. Vous pouvez vous y abonner en utilisant window.addEventListener ou via les méthodes de callback du gestionnaire de chatbot.

Comment masquer le bouton de chat par défaut et ouvrir le chatbot par programmation ?

Utilisez l'option de configuration showChatButton: false pour masquer le bouton par défaut, puis appelez chatbotManager.openChat() pour ouvrir le chatbot selon vos propres conditions — par exemple, lors d'un clic sur un bouton personnalisé.

Quelle est la différence entre les méthodes de callback du gestionnaire et window.addEventListener ?

Les deux approches fonctionnent. Les méthodes de callback du gestionnaire (par exemple, chatbotManager.onMessageSent(fn)) sont appelées à l'intérieur du callback init et sont liées à l'instance du gestionnaire. L'approche window.addEventListener (par exemple, window.addEventListener('onFHMessageSent', fn)) peut être configurée n'importe où dans votre page, même avant le chargement du chatbot.

Comment transmettre des données personnalisées au chatbot à l'aide de variables de flux ?

Utilisez l'option de configuration flowVariables dans setConfig() pour transmettre des paires clé-valeur telles que l'ID utilisateur, l'e-mail ou l'URL de la page. Ces variables deviennent disponibles dans le flux de votre chatbot pour des réponses personnalisées.

Quelles données sont disponibles dans les gestionnaires d'événements ?

Les événements contenant des données les incluent dans event.detail.metadata. Par exemple, onFHMessageSent inclut le contenu du message et l'horodatage, onFHMessageReceived inclut le flow_id, le message_id et le texte du message, et onFHFeedback inclut le message_id et indique si le feedback était positif ou négatif.