Integrazioni
FlowHunt si integra con i tuoi strumenti preferiti di assistenza clienti e produttività, così puoi usufruire di chatbot AI e automazione ovunque. Sfoglia la nos...
2 min di lettura
Integrations
AI Chatbot
+7
La FlowHunt JS API ti offre il pieno controllo su come il tuo chatbot si integra con il tuo sito web. Utilizzando il codice di integrazione v2, puoi incorporare il chatbot, iscriverti agli eventi di ciclo di vita e interazione, passare dati dinamici tramite variabili di flusso, tracciare le interazioni con parametri URL e controllare la finestra di chat in modo programmatico.
Questa guida copre ogni aspetto della JS API con esempi di codice che puoi copiare e adattare al tuo progetto.
Codice di integrazione (v2)
Quando crei un chatbot in FlowHunt, ottieni uno snippet di integrazione. Copialo e incollalo nel tuo HTML subito prima del tag di chiusura </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>
Sostituisci YOUR_CHATBOT_ID e YOUR_WORKSPACE_ID con i valori dal tuo pannello di controllo FlowHunt. L’ID del chatbot nel nome della variabile globale (window.FHChatbot_YOUR_CHATBOT_ID) utilizza underscore al posto dei trattini.
Sovrascrivere la configurazione con setConfig()
Prima di chiamare init(), puoi sovrascrivere le impostazioni predefinite del chatbot usando 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>
Opzioni di configurazione disponibili
| Option | Type | Descrizione |
|---|---|---|
headerTitle | string | Testo personalizzato del titolo dell’intestazione |
maxWindowWidth | string | Larghezza massima della finestra di chat (ad esempio, '700px') |
maxWindowHeight | string | Altezza massima della finestra di chat |
inputPlaceholder | string | Testo segnaposto per il campo di inserimento dei messaggi |
showChatButton | boolean | Mostra o nascondi il pulsante di chat flottante predefinito |
openChatPanel | boolean | Apri automaticamente il pannello di chat al caricamento della pagina |
flowVariables | object | Coppie chiave-valore di dati personalizzati passati al flusso |
urlSuffix | string | Stringa di query aggiunta a tutti gli URL generati dal chatbot |
cookieConsent | boolean | Abilita la persistenza della sessione tramite cookie |
embedded | string | Attiva la modalità incorporata (nessun pulsante di chiusura) |
theme | string | Modalità tema |
Pronto a far crescere il tuo business?
Inizia oggi la tua prova gratuita e vedi i risultati in pochi giorni.
Variabili di flusso: Passare dati dinamici
Le variabili di flusso ti permettono di inviare dati personalizzati dal tuo sito web al flusso del chatbot. Questo consente conversazioni personalizzate basate sul contesto dell’utente.
window.FHChatbot_YOUR_CHATBOT_ID.setConfig({
flowVariables: {
userId: getCurrentUserId(),
userEmail: getCurrentUserEmail(),
currentPage: window.location.pathname,
plan: 'enterprise'
}
});
Una volta impostate, queste variabili sono accessibili all’interno della logica del flusso del chatbot, permettendoti di personalizzare le risposte, instradare le conversazioni o passare il contesto agli agenti IA.
Suffisso URL: Tracciare le interazioni del chatbot
Il parametro urlSuffix aggiunge una stringa di query a ogni URL generato dal chatbot. Questo è utile per tracciare il traffico originato dal chatbot negli strumenti di analisi:
window.FHChatbot_YOUR_CHATBOT_ID.setConfig({
urlSuffix: '?utm_source=chatbot&utm_medium=widget'
});
Casi d’uso:
- Tracciare le conversioni dalle interazioni del chatbot in Google Analytics.
- Analizzare il comportamento degli utenti dopo aver interagito con il chatbot.
- Attribuire le campagne che stimolano l’engagement del chatbot.
Iscriviti alla nostra newsletter
Ricevi gratuitamente gli ultimi consigli, tendenze e offerte.
Riferimento degli eventi
La FlowHunt JS API invia 10 eventi personalizzati sull’oggetto window. Tutti gli eventi utilizzano l’API CustomEvent
con bubbles: true e composed: true.
onFHChatbotReady
Viene attivato quando il widget del chatbot è completamente renderizzato e pronto per l’uso.
- Dati dell’evento: Nessuno
- Quando: Dopo che il DOM del widget è montato e il pulsante di chat è visibile.
onFHChatbotSessionCreated
Viene attivato quando viene creata una nuova sessione di chat sul server. Si attiva anche quando la sessione viene riavviata.
- Dati dell’evento: Nessuno
- Quando: Dopo una chiamata API di creazione sessione riuscita.
onFHChatbotWindowOpened
Viene attivato quando l’utente apre la finestra di chat.
- Dati dell’evento: Nessuno
- Quando: Il pannello di chat diventa visibile.
- Nota: Non viene attivato in modalità incorporata.
onFHChatbotWindowClosed
Viene attivato quando l’utente chiude la finestra di chat.
- Dati dell’evento: Nessuno
- Quando: Il pannello di chat viene nascosto.
- Nota: Non viene attivato in modalità incorporata.
onFHMessageSent
Viene attivato quando l’utente invia un messaggio.
- Dati dell’evento (
event.detail.metadata):
{
"content": "Hello, I need help with...",
"createdAt": "2026-02-19T10:30:00.000Z"
}
onFHMessageReceived
Viene attivato quando il chatbot riceve e visualizza una risposta.
- Dati dell’evento (
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"
}
}
Il campo sender è opzionale e presente solo quando è coinvolto un agente umano.
onFHFormDataSent
Viene attivato quando l’utente invia dati del modulo tramite il chatbot.
- Dati dell’evento (
event.detail.metadata):
{
"objectData": { "name": "John", "email": "john@example.com" },
"createdAt": "2026-02-19T10:31:00.000Z"
}
onFHFeedback
Viene attivato quando un utente dà un feedback positivo o negativo su un messaggio del chatbot.
- Dati dell’evento (
event.detail.metadata):
{
"message_id": "msg_456",
"content": "Optional feedback text",
"feedback": "P"
}
Il valore di feedback è "P" per positivo (pollice in su) o "N" per negativo (pollice in giù).
onFHToolCall
Viene attivato quando uno strumento o un’azione viene eseguito durante l’elaborazione del flusso.
- Dati dell’evento (
event.detail.metadata):
{
"metadata": {
"flow_id": "abc123",
"message_id": "msg_789",
"message": "Calling search API..."
},
"createdAt": "2026-02-19T10:32:00.000Z"
}
Nota: Viene attivato solo nelle modalità flowAssistant e flowAssistantV3, non nella modalità chatbot standard.
onFHError
Viene attivato quando si verifica un errore durante il funzionamento del chatbot.
- Dati dell’evento (
event.detail.metadata):
{
"metadata": {
"flow_id": "abc123",
"message_id": "msg_err",
"message": "Flow execution failed"
},
"createdAt": "2026-02-19T10:33:00.000Z"
}
Iscrizione agli eventi
Ci sono due modi per iscriversi agli eventi del chatbot.
Metodo 1: Listener di eventi Window
Usa window.addEventListener ovunque nella tua pagina. Questo funziona anche prima del caricamento del 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>
Per smettere di ascoltare un evento, usa removeEventListener con lo stesso riferimento alla funzione:
var handleMessage = function(event) {
console.log(event.detail.metadata);
};
window.addEventListener('onFHMessageReceived', handleMessage);
// Later, when you want to stop listening:
window.removeEventListener('onFHMessageReceived', handleMessage);
Metodo 2: Metodi di callback del gestore
All’interno del callback init(), usa i metodi integrati del gestore del 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);
});
});
Riferimento dei metodi del gestore
| Method | Parameters | Descrizione |
|---|---|---|
onSessionCreated(fn) | fn: () => void | Ascolta la creazione della sessione |
onWindowOpened(fn) | fn: () => void | Ascolta l’apertura della finestra |
onWindowClosed(fn) | fn: () => void | Ascolta la chiusura della finestra |
onMessageSent(fn) | fn: (event) => void | Ascolta i messaggi dell’utente |
onMessageReceived(fn) | fn: (event) => void | Ascolta le risposte del bot |
onFormDataSent(fn) | fn: (event) => void | Ascolta gli invii di moduli |
onFeedback(fn) | fn: (event) => void | Ascolta il feedback dell’utente |
onToolCall(fn) | fn: (event) => void | Ascolta le esecuzioni degli strumenti |
onError(fn) | fn: (event) => void | Ascolta gli errori |
openChat() | — | Apre il pannello di chat |
closeChat() | — | Chiude il pannello di chat |
Attivazione personalizzata della chat: Nascondere il pulsante e aprire al clic
Per controllare completamente quando il chatbot appare, nascondi il pulsante flottante predefinito e apri la chat in modo programmatico — ad esempio, dal tuo pulsante personalizzato.
Esempio completo
<!-- 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>
Mostrare un pulsante personalizzato solo quando il chatbot è pronto
Puoi combinare l’attivazione nascosta con i listener di eventi per creare interazioni avanzate:
<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>
Esempio di integrazione completo
Un esempio funzionante completo che dimostra le sovrascritture di configurazione, il tracciamento degli eventi e l’attivazione personalizzata della chat insieme:
<!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>
