Flussi conversazionali
Trigger, condizioni, azioni, rami e fallback dei flussi guidati, con esempi completi di prenotazione e preventivo.
Un flusso conversazionale è un percorso deterministico che prende il controllo della conversazione quando si verifica un trigger. Serve dove la generazione libera del modello non è accettabile: raccolta di dati, prenotazioni, verifiche di identità, procedure regolamentate.
Flussi e modello convivono
Il flusso non sostituisce il modello: lo affianca. Fuori dai flussi l'assistente risponde liberamente sulla base della knowledge base; dentro un flusso segue esattamente i passi che hai definito.
Prima di iniziare
- Progetto esistente con modello e avatar
- Strumenti registrati per le azioni che richiedono dati esterni
- Widget pubblicati se il flusso deve mostrare schede
Creare un flusso
Nome e priorità
Assegna un nome e una priorità da 1 a 100. Se più flussi si attivano contemporaneamente vince quello con priorità più alta.
Definisci il trigger
Scegli cosa deve accadere perché il flusso parta.
Aggiungi condizioni
Restringi l'attivazione con condizioni sul contesto: canale, lingua, orario, utente riconosciuto.
Costruisci i passi
Trascina le azioni sul canvas e collegale. Ogni azione ha un ramo di successo e uno di errore.
Collauda e pubblica
Usa il simulatore, poi pubblica il progetto.
Trigger
| Tipo | Si attiva quando | Configurazione |
|---|---|---|
| Parola chiave | Il messaggio contiene una delle espressioni indicate | Elenco di termini, corrispondenza esatta o parziale |
| Intento | Il modello classifica il messaggio in un intento | Nome dell'intento e soglia di confidenza |
| Evento | Accade un evento della sessione o del sito | session.started, handover.requested, page.viewed, evento personalizzato |
| Orario | La conversazione ricade in una fascia oraria | Giorni, fascia, fuso orario |
| Manuale | Un operatore o un'API lo avvia | Chiave del flusso |
{
"type": "intent",
"intent": "prenotare_visita",
"min_confidence": 0.72,
"examples": [
"vorrei prenotare una visita",
"come posso fissare un appuntamento",
"avete posto per una ecografia",
"quando posso venire per il controllo"
]
}Soglia di confidenza
Sotto 0.60 il flusso si attiva su richieste non pertinenti; sopra 0.85 non si
attiva quasi mai. Parti da 0.72 e correggi osservando i log delle sessioni.
Condizioni
Le condizioni sono valutate dopo il trigger e possono essere combinate con AND e OR.
| Variabile | Tipo | Esempio di condizione |
|---|---|---|
channel | stringa | channel eq "whatsapp" |
locale | stringa | locale in ["it", "en"] |
user.isAuthenticated | booleano | user.isAuthenticated eq true |
user.metadata.piano | stringa | user.metadata.piano eq "premium" |
session.messageCount | numero | session.messageCount gte 3 |
page.url | stringa | page.url contains "/prenotazioni" |
businessHours | booleano | businessHours eq false |
context.prestazione | stringa | context.prestazione exists |
Azioni
| Azione | Effetto | Parametri principali |
|---|---|---|
| Rispondi | Invia un messaggio testuale o un widget | text, widget, quickReplies |
| Chiedi | Pone una domanda e salva la risposta in una variabile | question, variable, validation, retries |
| Chiama strumento | Invoca uno strumento registrato | tool, params, resultVariable |
| Condizione | Biforca il percorso | expression, onTrue, onFalse |
| Escala a operatore | Richiede l'handover umano | queue, summary, priority |
| Invia webhook | Notifica un sistema esterno | webhookId, payload |
| Imposta variabile | Scrive nel contesto della sessione | name, value |
| Attendi | Sospende il flusso per un intervallo | durationMs |
| Chiudi | Termina il flusso e la sessione | closingMessage, outcome |
Variabili di contesto
Le variabili raccolte durante il flusso restano disponibili per tutta la sessione e vengono incluse nei payload dei webhook.
| Ambito | Prefisso | Durata | Esempio |
|---|---|---|---|
| Sessione | context. | Fino alla chiusura della sessione | context.prestazione |
| Utente | user. | Persistente, se l'utente è identificato | user.email |
| Sistema | system. | Sola lettura | system.now, system.channel |
| Risultato strumento | variabile assegnata | Fino a sovrascrittura | disponibilita.giorni |
Nei testi le variabili si interpolano con doppie parentesi graffe, ad esempio
Ho prenotato la tua {{context.prestazione}} per il {{context.data}}.
Rami e fallback
Ogni azione espone tre uscite.
| Uscita | Quando viene percorsa | Comportamento predefinito |
|---|---|---|
| Successo | L'azione è andata a buon fine | Passo successivo |
| Errore | Strumento in errore o timeout | Messaggio di scusa e chiusura |
| Nessuna risposta | L'utente non risponde entro il timeout | Sollecito, poi abbandono |
Impostazioni consigliate a livello di flusso:
| Parametro | Valore consigliato |
|---|---|
| Tentativi per domanda | 2 |
| Timeout di attesa risposta | 180 secondi su web, 24 ore su WhatsApp |
| Comportamento all'abbandono | Salva le variabili raccolte e invia webhook session.abandoned |
| Parola di uscita | annulla |
| Escalation automatica | Dopo 2 errori consecutivi |
Prevedi sempre l'uscita
Ogni flusso deve poter essere abbandonato. Aggiungi in ogni domanda l'istruzione "Scrivi annulla per interrompere" e un ramo di uscita esplicito.
Esempio completo: prenotazione di una visita
Trigger
Intento prenotare_visita con confidenza minima 0.72.
Condizione aggiuntiva: channel in ["web", "whatsapp"].
Chiedi la prestazione
Domanda: "Che tipo di visita o esame ti serve?"
Variabile: context.prestazione.
Risposte rapide: Visita cardiologica, Ecografia, Analisi del sangue, Altro.
Validazione: la risposta deve corrispondere a una prestazione a catalogo;
in caso contrario mostra il widget cardPrestazioni con l'elenco.
Chiama lo strumento verifica_disponibilita
Parametri: prestazione da context.prestazione, dataInizio da system.now,
giorni uguale a 14.
Risultato in disponibilita.
Ramo di errore: messaggio di scusa e passaggio a operatore.
Condizione sulla disponibilità
Espressione: disponibilita.giorni empty.
Se vera: proponi la lista di attesa e raccogli il recapito, poi chiudi.
Se falsa: prosegui.
Rispondi con il widget slot_disponibili
Mostra il widget alimentato dalla variabile disponibilita.
La selezione di uno slot scrive context.slotId e prosegue il flusso.
Raccogli i dati del paziente
Tre domande consecutive: nome e cognome, numero di telefono, email.
Validazione: telefono con prefisso italiano, email con formato valido.
Salta le domande se user.isAuthenticated è vero.
Consenso al trattamento
Mostra un widget form con un checkbox obbligatorio e il link
all'informativa privacy. Salva l'esito in context.consenso.
Chiama lo strumento crea_prenotazione
Parametri: slotId, paziente, consenso.
Risultato in prenotazione.
Ramo di errore: comunica il problema, proponi un orario alternativo o l'operatore.
Conferma e chiudi
Mostra il widget cardVisitConfirmed con i dati di prenotazione.
Invia il webhook booking.created.
Chiudi il flusso con esito completed.
Esempio completo: richiesta di preventivo
Trigger
Parole chiave: preventivo, quanto costa, offerta, listino.
Condizione: businessHours indifferente, il flusso funziona sempre.
Qualifica la richiesta
Domanda: "Di quale servizio hai bisogno?" con risposte rapide dai tuoi tre servizi
principali. Variabile context.servizio.
Raccogli il dimensionamento
Domanda: "Quante postazioni o utenti devi coprire?"
Variabile context.volume, validazione numerica tra 1 e 10000.
Condizione sul valore
Espressione: context.volume gte 100.
Se vera: imposta context.priorita a alta e instrada verso il commerciale senior.
Se falsa: prosegui con il preventivo automatico.
Chiama lo strumento calcola_preventivo
Parametri: servizio, volume.
Risultato in preventivo. In caso di errore raccogli i dati e apri un ticket.
Mostra la stima e raccogli i contatti
Widget card con importo formattato via currency_format.
Poi domanda su ragione sociale, email aziendale e telefono.
Invia webhook e chiudi
Invia lead.created al CRM con tutte le variabili di contesto.
Chiudi con: "Ti ho inviato il preventivo via email. Un nostro consulente ti contatta
entro un giorno lavorativo."
Collaudo del flusso
Il simulatore esegue il flusso senza generare sessioni reali né webhook di produzione.
| Funzione | Descrizione |
|---|---|
| Esecuzione passo-passo | Avanza un'azione alla volta mostrando il contesto |
| Ispettore variabili | Elenco delle variabili con valore corrente |
| Strumenti simulati | Sostituisci la risposta reale con un JSON di prova |
| Forzatura dei rami | Percorri il ramo di errore senza provocare un guasto |
| Trascrizione | Esporta la conversazione simulata in formato testo |
Casi da collaudare sempre
Percorso ideale, strumento in errore, nessuna disponibilità, utente che scrive "annulla", utente che non risponde, utente che cambia idea a metà flusso.
Pubblicazione
I flussi seguono il ciclo di pubblicazione del progetto: le modifiche sono immediate
in development e richiedono la pubblicazione in staging e production.
Le sessioni già dentro un flusso completano l'esecuzione con la versione precedente.
Integrazione con WhatsApp
I flussi funzionano su WhatsApp con alcune differenze imposte dal canale.
| Aspetto | Web | |
|---|---|---|
| Widget interattivi | Rendering completo | Convertiti in liste e pulsanti nativi |
| Pulsanti per messaggio | Illimitati | Massimo 3 |
| Voci di lista | Illimitate | Massimo 10 |
| Timeout di risposta | 180 secondi | 24 ore |
| Riapertura fuori finestra | Immediata | Richiede un template approvato |
| Allegati | Sì | Sì, con limiti di dimensione |
Finestra di 24 ore
Fuori dalla finestra di servizio di 24 ore puoi ricontattare l'utente solo con un template approvato da Meta. Configura i template in Integrazioni.
Chiave del flusso per l avvio da API
prenotazione-visitaUsala nel campo flow_key dell endpoint di avvio flusso.
/identity/v1/sessions/{sessionId}/flows/startAPI KeyAvvia manualmente un flusso su una sessione esistente.
Passi successivi
- Strumenti — registra le funzioni chiamate dai flussi.
- Widget Builder — costruisci le schede mostrate nei passi.
- Automazioni e RPA — collega i flussi ai robot software.