Riferimento completo per l’integrazione della FlowHunt JS API v2. Incorpora il chatbot, iscriviti a tutti gli 11 eventi, utilizza le variabili di flusso, attiva il trigger Chat Hook a metà conversazione con sendHook(), traccia le interazioni con i parametri URL e controlla la finestra di chat in modo programmatico.
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, attivare il trigger Chat Hook a metà conversazione con sendHook(), 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.
Copia e incolla lo snippet qui sotto nel tuo HTML subito prima del tag di chiusura </body>. Sostituisci YOUR_CHATBOT_ID e YOUR_WORKSPACE_ID con i valori dalle impostazioni del tuo chatbot FlowHunt.
<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>
L’ID del chatbot nel nome della variabile globale (window.FHChatbot_YOUR_CHATBOT_ID) utilizza underscore al posto dei trattini.
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 initialised with custom config
});
};
if (currentScript && currentScript.parentNode) {
currentScript.parentNode.insertBefore(script, currentScript.nextSibling);
} else {
document.head.appendChild(script);
}
</script>
| Opzione | Tipo | 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. I valori possono essere di qualsiasi tipo serializzabile in JSON (string, number, boolean, object, array). |
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 |
flowVariables vengono unite a ogni sessione creata dal chatbot. Vengono tipicamente utilizzate come contesto statico (noto al caricamento della pagina): l’ID dell’utente, il piano, la lingua corrente, ecc.
window.FHChatbot_YOUR_CHATBOT_ID.setConfig({
flowVariables: {
userId: getCurrentUserId(),
userEmail: getCurrentUserEmail(),
currentPage: window.location.pathname,
plan: 'enterprise',
},
});
Se l’utente naviga dopo che la chat è stata aperta, i valori passati qui diventano obsoleti. Per aggiornarli a metà conversazione, chiama
chatbotManager.sendHook()conoptions.flowVariables— vedi Comunicazione host → flusso a metà conversazione qui sotto.
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:
Inizia oggi la tua prova gratuita e vedi i risultati in pochi giorni.
Aggiunto in aprile 2026 come parte della funzionalità FlowHunt Chat Hook.
Nelle applicazioni a pagina singola la finestra di chat in genere rimane aperta mentre l’utente naviga tra le schermate. Una volta che la chat è in esecuzione, le flowVariables passate tramite setConfig() diventano obsolete e non c’è modo di informare il flusso su qualcosa che è accaduto sulla pagina host. Un singolo metodo del gestore — sendHook(name, payload, options?) — copre entrambi i casi d’uso “attiva un trigger” e “aggiorna semplicemente il contesto”:
name e (opzionalmente) un payload per attivare il trigger Chat Hook del flusso. L’autore del flusso inserisce un nodo Chat Hook sul canvas e si dirama su {ChatHook.hook_name} per decidere cosa fare.options.flowVariables per unire le variabili di sessione contemporaneamente — i valori vengono persistiti prima che il trigger si attivi e rimangono disponibili per il resto della sessione.options.flowVariables viene comunque unito, ma nessun trigger viene eseguito e nessun credito viene addebitato. Questo significa che le pagine host possono chiamare sendHook() in modo ottimistico senza sapere se l’autore del flusso ha già collegato un trigger.sendHook() è un no-op sicuro prima che la sessione esista (memorizzato internamente in un buffer e svuotato una volta creata la sessione) e non lancia mai eccezioni alla pagina host — gli errori di rete vengono registrati solo tramite console.warn.
Limiti lato server e lato client che si applicano a sendHook(). Violarli non è un crash — il backend restituisce HTTP 422 e il gestore registra tramite console.warn senza lanciare eccezioni.
| Vincolo | Limite | Dove viene applicato | In caso di violazione |
|---|---|---|---|
Lunghezza di name in sendHook | 1–256 caratteri | Backend (Pydantic) | HTTP 422, il trigger non si attiva |
Numero di chiavi in options.flowVariables | ≤ 64 | Backend (Pydantic) | HTTP 422, nulla viene persistito |
Lunghezza di ogni chiave in options.flowVariables | ≤ 128 caratteri | Backend (Pydantic) | HTTP 422, nulla viene persistito |
| Chiamate pre-sessione bufferizzate dal gestore | 50 | Widget (nel browser) | La chiamata in coda più vecchia viene scartata e viene registrato un console.warn |
Il limite del buffer pre-sessione conta solo nelle pagine in cui la creazione della sessione fallisce indefinitamente (ad esempio, un errore di rete permanente). In condizioni normali la coda viene svuotata non appena si attiva onFHChatbotSessionCreated.
onFHError).hook_name, payload, flow_variables) agli step downstream che desideri attivare (Generator, Chat Output, Tool Calls, diramazioni condizionali su hook_name, ecc.).Il name che la pagina host passa a sendHook() è un’etichetta su cui il tuo flusso può diramarsi, non una chiave di routing — il backend non confronta i nomi con i nodi. Invece, il singolo trigger Chat Hook del flusso si attiva ed espone il nome come {ChatHook.hook_name}, che fai riferimento nella logica del tuo flusso per decidere cosa fare.
Esempio di prompt di sistema:
If {ChatHook.hook_name} is "screen_changed", briefly summarise the page at
{ChatHook.payload.url}. If it is "user_action", acknowledge the action and
update memory. Otherwise, continue the conversation normally.
Per un routing più complesso, collega uno step condizionale su {ChatHook.hook_name} e diramati in più percorsi downstream.
chatbotManager.sendHook(name, payload, options?)chatbotManager.sendHook(
name: string,
payload?: Record<string, unknown>,
options?: { flowVariables?: Record<string, unknown> }
): Promise<void>;
Argomenti
| Argomento | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
name | string | sì | Etichetta inoltrata al flusso come {ChatHook.hook_name}. Il trigger si attiva indipendentemente dal valore; la logica del tuo flusso si dirama su di esso. |
payload | object | no | Payload JSON consegnato al trigger come {ChatHook.payload}. Validato rispetto allo schema del nodo se abilitato. Predefinito {}. |
options.flowVariables | object | no | Variabili di sessione da unire prima che il trigger si attivi. Disponibili agli step downstream e ai futuri messaggi dell’utente. |
Comportamento
onFHChatbotSessionCreated è sicuro; la chiamata viene bufferizzata e svuotata una volta che la sessione esiste. Il buffer ha un limite — vedi Limiti di input sopra.sendHook() in modo ottimistico prima che l’autore del flusso colleghi un trigger. options.flowVariables viene comunque persistito anche in quel caso, quindi la stessa chiamata serve come aggiornamento del solo contesto.onFHError).name e options.flowVariables sono limitati — vedi Limiti di input sopra. Le violazioni restituiscono HTTP 422 e nulla viene persistito.onFHChatbotFlowVariablesUpdate se è stato fornito options.flowVariables (vedi Riferimento degli eventi).console.warn.Esempio — suggerimento proattivo sulla navigazione SPA
window.FHChatbot_YOUR_CHATBOT_ID.init(function (chatbotManager) {
window.addEventListener('hashchange', function () {
chatbotManager.sendHook('screen_changed', {
url: window.location.href,
screen_name: getScreenName(),
}, {
flowVariables: { current_page_url: window.location.href },
});
});
});
Esempio — aggiornamento del solo contesto (nessun Chat Hook collegato)
Se il flusso non ha un trigger Chat Hook, la chiamata è un 200 silenzioso — quindi la stessa API può mantenere flow_variables sincronizzate senza attivare nulla:
window.FHChatbot_YOUR_CHATBOT_ID.init(function (chatbotManager) {
window.addEventListener('hashchange', function () {
chatbotManager.sendHook('navigate', {}, {
flowVariables: {
current_page_url: window.location.href,
screen_name: getScreenName(),
},
});
});
});
{ChatHook.hook_name} e {ChatHook.payload.foo} — i valori passati tramite sendHook('x', { foo: 1 }) sono esposti sul percorso di esecuzione del trigger Chat Hook. Disponibili solo sul percorso avviato dall’attivazione dell’hook.{flow_variables.foo} — i valori passati tramite options.flowVariables vengono uniti al bag delle variabili della sessione prima che il trigger si attivi. Ogni percorso di esecuzione (inclusi i normali messaggi utente attivati da Chat Input) può leggerli.Se vuoi che il prossimo messaggio dell’utente veda un nuovo valore, mettilo in options.flowVariables — il payload da solo influisce solo sull’esecuzione avviata da quell’hook.
La FlowHunt JS API invia 11 eventi personalizzati sull’oggetto window. Tutti gli eventi utilizzano l’API CustomEvent
con bubbles: true e composed: true.
onFHChatbotReadyViene attivato quando il widget del chatbot è completamente renderizzato e pronto per l’uso.
onFHChatbotSessionCreatedViene attivato quando viene creata una nuova sessione di chat sul server.
event.detail.sessionId — l’ID della sessione appena creata.onFHChatbotWindowOpenedViene attivato quando l’utente apre la finestra di chat. Non viene attivato in modalità incorporata.
onFHChatbotWindowClosedViene attivato quando l’utente chiude la finestra di chat. Non viene attivato in modalità incorporata.
onFHMessageSentViene attivato quando l’utente invia un messaggio.
event.detail.metadata = {
content: 'Hello, I need help with...',
createdAt: '2026-02-19T10:30:00.000Z',
};
onFHMessageReceivedViene attivato quando il chatbot riceve e visualizza una risposta.
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',
},
};
sender è opzionale e presente solo quando è coinvolto un agente umano.
onFHFormDataSentViene attivato quando l’utente invia dati del modulo tramite il chatbot.
event.detail.metadata = {
objectData: { name: 'John', email: 'john@example.com' },
createdAt: '2026-02-19T10:31:00.000Z',
};
onFHFeedbackViene attivato quando un utente dà un feedback positivo o negativo su un messaggio del chatbot.
event.detail.metadata = {
message_id: 'msg_456',
content: 'Optional feedback text',
feedback: 'P', // 'P' = positive, 'N' = negative
};
onFHToolCallViene attivato quando uno strumento o un’azione viene eseguito durante l’elaborazione del flusso. Attivato solo nelle modalità flowAssistant e flowAssistantV3.
event.detail.metadata = {
metadata: {
flow_id: 'abc123',
message_id: 'msg_789',
message: 'Calling search API...',
},
createdAt: '2026-02-19T10:32:00.000Z',
};
onFHErrorViene attivato quando si verifica un errore durante il funzionamento del chatbot.
event.detail.metadata = {
metadata: {
flow_id: 'abc123',
message_id: 'msg_err',
message: 'Flow execution failed',
},
createdAt: '2026-02-19T10:33:00.000Z',
};
onFHChatbotFlowVariablesUpdateAggiunto in aprile 2026.
Viene attivato dopo una chiamata chatbotManager.sendHook(...) riuscita che ha fornito options.flowVariables. Non viene attivato per chiamate sendHook() che omettono flowVariables.
event.detail = {
variables: {
current_page_url: 'https://example.com/products',
screen_name: 'products',
},
};
Usalo per osservare le variabili unite (ad esempio per sincronizzare il tuo stato lato host, per il debug o per ri-renderizzare un elemento UI che dipende dagli stessi dati).
Ricevi gratuitamente gli ultimi consigli, tendenze e offerte.
Ci sono due modi per iscriversi agli eventi del chatbot.
Usa window.addEventListener ovunque nella tua pagina. Questo funziona anche prima del caricamento del chatbot:
<script>
document.addEventListener('DOMContentLoaded', function () {
window.addEventListener('onFHChatbotReady', function () {
console.log('Chatbot is ready');
});
window.addEventListener('onFHChatbotSessionCreated', function (event) {
console.log('Session created:', event.detail.sessionId);
});
window.addEventListener('onFHChatbotWindowOpened', function () {
console.log('Chat window opened');
});
window.addEventListener('onFHChatbotWindowClosed', function () {
console.log('Chat window closed');
});
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);
});
window.addEventListener('onFHFeedback', function (event) {
var fb = event.detail.metadata;
console.log('Feedback on message', fb.message_id, ':', fb.feedback);
});
window.addEventListener('onFHToolCall', function (event) {
console.log('Tool called:', event.detail.metadata);
});
window.addEventListener('onFHError', function (event) {
console.error('Chatbot error:', event.detail.metadata);
});
window.addEventListener('onFHChatbotFlowVariablesUpdate', function (event) {
console.log('Variables merged:', event.detail.variables);
});
});
</script>
Per rimuovere un listener, mantieni il riferimento al gestore:
var handleMessage = function (event) {
console.log(event.detail.metadata);
};
window.addEventListener('onFHMessageReceived', handleMessage);
// Later …
window.removeEventListener('onFHMessageReceived', handleMessage);
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);
});
});
| Metodo | Parametri | 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 |
sendHook(name, payload?, options?) (nuovo) | name: string, payload?: object, options?: { flowVariables?: object } | Attiva il trigger Chat Hook nel flusso in esecuzione (oppure unisce silenziosamente options.flowVariables se nessun trigger è collegato) |
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.
<button id="my-chat-button">Chat with us</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) {
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>
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>
window.addEventListener('onFHChatbotReady', function () {
document.getElementById('open-chat').style.display = 'block';
});
</script>
<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>
Un esempio funzionante completo che dimostra le sovrascritture di configurazione, il tracciamento degli eventi, l’attivazione personalizzata della chat e il nuovo metodo sendHook() 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 (event) {
console.log('New chat session started:', event.detail.sessionId);
});
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('onFHChatbotFlowVariablesUpdate', function (event) {
console.log('Context updated:', event.detail.variables);
});
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',
current_page_url: window.location.href,
},
urlSuffix: '?utm_source=chatbot',
});
window.FHChatbot_YOUR_CHATBOT_ID.init(function (chatbotManager) {
// Open / close from custom buttons
document.getElementById('open-chat-btn')
.addEventListener('click', function () {
chatbotManager.openChat();
});
document.getElementById('close-chat-btn')
.addEventListener('click', function () {
chatbotManager.closeChat();
});
// Keep the flow's context in sync with SPA navigation and
// optionally fire the Chat Hook trigger (if the flow has one wired).
// If the flow has no Chat Hook, the call is a silent 200 — the
// flow_variables still get merged, so the same line covers both
// "notify the flow" and "just update context".
window.addEventListener('hashchange', function () {
chatbotManager.sendHook('screen_changed', {
url: window.location.href,
}, {
flowVariables: { current_page_url: window.location.href },
});
});
});
};
if (currentScript && currentScript.parentNode) {
currentScript.parentNode.insertBefore(script, currentScript.nextSibling);
} else {
document.head.appendChild(script);
}
</script>
</body>
</html>
Guida tecnica per padroneggiare l'integrazione avanzata di FlowHunt con LiveAgent: targeting della lingua, soppressione markdown, filtro antispam, versionamento...
FlowHunt 2.6.12 introduce l'integrazione con Slack, la classificazione delle intenzioni e il modello Gemini, migliorando le funzionalità del chatbot AI, la comp...
Integra FlowHunt con interactive-mcp per abilitare una comunicazione sicura e in tempo reale tra modelli linguistici di grandi dimensioni e utenti su macchine l...
Consenso Cookie
Usiamo i cookie per migliorare la tua esperienza di navigazione e analizzare il nostro traffico. See our privacy policy.