🇮🇹 IT

5. Questionari

I Questionari ti permettono di creare moduli conversazionali passo-passo e distribuirli come incorporamento web, tramite WhatsApp o come chiamata vocale basata su AI. Ogni questionario e un grafo di nodi connessi — domande, logica di ramificazione, effetti collaterali HTTP e trigger di workflow — che guidano il rispondente dall'inizio al completamento.

Pagina elenco questionari — nome, badge di stato, conteggio risposte, data ultimo aggiornamento e pulsante "Nuovo Questionario".

Panoramica

A differenza dei Workflow, che vengono attivati da eventi e vengono eseguiti lato server in background, i Questionari sono rivolti al rispondente: una persona risponde a ogni domanda a turno, e Flusso avanza la sessione attraverso il grafo in base alle risposte. Un questionario puo essere incorporato in qualsiasi pagina web o inviato a un numero WhatsApp, senza che i rispondenti debbano avere un account Flusso.

Ogni volta che qualcuno avvia un questionario viene creata una sessione. La colonna Risposte nella pagina elenco mostra il numero totale di sessioni per ogni questionario.

Concetti chiave:
Sessione — il percorso di un singolo rispondente attraverso un questionario dall'inizio alla fine.
Nodo iniziale — il nodo da cui inizia ogni sessione (contrassegnato da un bordo ambra).
Nodo di completamento — il nodo terminale che conclude la sessione con un messaggio di successo o fallimento.

Pagina Elenco Questionari

Naviga su Questionari nella barra laterale sinistra per vedere tutti i tuoi questionari. L'elenco mostra:

Colonna	Descrizione
Nome	Il nome visualizzato del questionario. Clicca per aprire l'editor.
Stato	Stato attuale: Bozza, Attivo o Archiviato.
Risposte	Numero di sessioni avviate (ogni rispondente crea una sessione).
Aggiornato	Quando il questionario e stato salvato l'ultima volta.

Usa la barra di ricerca in alto per filtrare per nome. Clicca Nuovo Questionario nell'angolo in alto a destra per crearne uno.

Stati del Questionario

Stato	Significato
Bozza	In fase di modifica. Non accessibile ai rispondenti; l'incorporamento web e inattivo.
Attivo	Pubblicato e in grado di ricevere risposte. L'incorporamento web funziona; la distribuzione WhatsApp e le Chiamate Vocali AI sono abilitate.
Archiviato	Conservato come riferimento ma non accetta piu risposte.

Creazione di un Questionario

Clicca "Nuovo Questionario" Si apre la finestra di creazione. Inserisci un Nome (obbligatorio) e una Descrizione opzionale, poi conferma.
L'editor si apre automaticamente Verrai portato direttamente all'editor del grafo per il nuovo questionario.
Aggiungi un nodo iniziale Trascina un nodo Domanda dalla palette a sinistra sul canvas. Passa il mouse sopra il nodo e clicca l'icona del fulmine per contrassegnarlo come nodo iniziale (bordo ambra).
Costruisci il grafo delle domande Collega i nodi domanda con archi dalle porte delle risposte. Aggiungi un nodo Completamento alla fine di ogni ramo.
Salva e attiva Clicca Salva nella barra superiore. Cambia il selettore di stato su Attivo quando sei pronto a ricevere risposte.

L'Editor del Questionario

L'editor utilizza lo stesso canvas del grafo dell'Editor Grafico dei Workflow: un canvas con griglia a punti con panoramica e zoom, una palette dei nodi a sinistra e una barra degli strumenti superiore. La barra superiore include anche un pulsante Tema che apre l'Editor del Tema, dove puoi personalizzare l'aspetto visivo dell'incorporamento web.

Editor grafico del questionario — Editor del questionario — canvas del grafo con nodi domanda, archi dalle porte delle risposte e barra superiore con nome, stato, Salva, Incorpora, AI, WhatsApp e pulsanti Chiamata Vocale.

Barra Superiore

Controllo	Descrizione
Campo nome	Modifica il nome del questionario direttamente inline.
Selettore stato	Passa tra Bozza, Attivo e Archiviato.
Salva	Salva tutte le modifiche del canvas.
Tema	Apre l'Editor del Tema per personalizzare colori, tipografia e stili degli elementi per l'incorporamento web.
</> Incorpora	Apre il pannello Incorpora per ottenere lo snippet web.
AI	Apre il pannello Configurazione AI per impostare il provider e il prompt del classificatore.
WhatsApp	Apre il pannello di configurazione della distribuzione WhatsApp.
Chiamata Vocale	Apre il pannello di configurazione della Chiamata Vocale AI.

Controlli del Canvas

Posizionare un nodo: Trascina dalla palette a sinistra sul canvas, oppure clicca un elemento della palette per posizionarlo al centro del canvas.
Collegare i nodi: Trascina da una porta di uscita (punto colorato sul bordo destro del nodo) alla porta di ingresso di un altro nodo.
Eliminare un arco: Clicca sull'arco per selezionarlo, poi premi Canc.
Panoramica: Trascinamento con tasto centrale o destro del mouse su un'area vuota del canvas.
Zoom: Ctrl + rotella del mouse, oppure usa i controlli zoom nell'angolo in basso a sinistra.
Azioni sul nodo: Passa il mouse sopra un nodo per visualizzare i pulsanti azione — configura (matita), imposta come iniziale (fulmine), clona (copia), elimina (cestino).

Impostare il Nodo Iniziale

Ogni questionario deve avere esattamente un nodo iniziale. Passa il mouse sopra il nodo che vuoi usare come punto di ingresso e clicca l'icona del fulmine. Il nodo acquisisce un bordo ambra per indicare che e il nodo iniziale. Ogni sessione inizia da questo nodo quando un rispondente apre il questionario.

Tipi di Nodo

Nodo Domanda

Presenta una domanda al rispondente e attende la risposta prima di avanzare. Il colore del nodo e indaco.

Campo	Descrizione
Testo della domanda	La domanda mostrata al rispondente.
Tipo di risposta	Controlla come il rispondente risponde e come vengono generate le porte di uscita (vedi sotto).

Tipi di Risposta e Porte di Uscita

Tipo di risposta	Porte di uscita	Note
Booleano (Si / No)	Si, No	Due porte fisse. Collega ciascuna a un ramo diverso.
Scelta Singola	Una porta per opzione	Definisci l'elenco delle scelte. Ogni scelta diventa una porta di uscita con nome.
Scelta Singola + Altro	Una porta per opzione, piu Altro	Come Scelta Singola ma aggiunge una porta "Altro" con testo libero per risposte che non corrispondono a nessuna opzione elencata.
Testo Libero	Risposta	Porta singola. Il rispondente digita una risposta libera. Quando collegato a un questionario WhatsApp con AI abilitata, il provider AI interpreta la risposta.
Valutazione Numerica	Una porta per valore (fino a 10), oppure Risposta	Il rispondente seleziona un numero da un intervallo configurabile Min/Max/Step (es. 1–5). Visualizzato come pulsanti orizzontali nell'incorporamento web. Se l'intervallo supera 10 valori, viene usata una singola porta Risposta.
Selezione Multipla	Risposta	Il rispondente sceglie una o piu opzioni da un elenco di caselle di controllo, soggetto a limiti Min/Max di selezione. Le chiavi selezionate vengono memorizzate come stringa separata da virgole.
Testo Validato	Risposta	Come Testo Libero, ma valida l'input rispetto a un formato: Email, Telefono o URL. Le voci non valide vengono rifiutate con un messaggio di errore. Nell'incorporamento web viene mostrato un suggerimento sul formato.
Scala Likert	Una porta per punto della scala	Il rispondente sceglie tra punti etichettati della scala (es. da "Fortemente in disaccordo" a "Fortemente d'accordo"). Ogni punto diventa una porta di uscita con nome per la ramificazione basata sul sentimento.

Allegati e FAQ

I nodi domanda supportano allegati (fino a 5 per nodo, max 10 MB ciascuno) e voci FAQ (fino a 20 per nodo). Configura entrambi dal pannello di configurazione del nodo domanda nell'editor.

Allegati: Le immagini appaiono come una galleria sopra i controlli di risposta nell'incorporamento web. I file non immagine (PDF, documenti) appaiono come schede file scaricabili. Formati consentiti: PDF, JPG, PNG, GIF, WebP, TXT, DOC, DOCX. I file vengono eliminati automaticamente quando il nodo o il questionario viene cancellato.
FAQ: Visualizzate come fisarmonica espandibile nell'incorporamento web. Su WhatsApp (Baileys), viene aggiunto un pulsante Aiuto alla domanda — toccandolo si ottiene il testo FAQ senza far avanzare la sessione.

Nodo di Completamento

Un nodo terminale che conclude la sessione. Il colore del nodo e verde. Ogni ramo nel grafo del questionario deve terminare con un Nodo di Completamento.

Campo	Descrizione
Stato	Successo o Fallimento — controlla l'icona e il colore mostrati al rispondente.
Messaggio di successo	Testo visualizzato quando la sessione termina con successo.
Messaggio di fallimento	Opzionale. Mostrato quando lo stato e Fallimento.
URL di reindirizzamento	Opzionale. Dopo aver mostrato il messaggio di completamento, l'incorporamento web reindirizza a questo URL.
Esportazione Google Sheets	Opzionale. Esporta automaticamente tutte le risposte raccolte in un foglio Google Sheets al completamento. Richiede una connessione Google OAuth. Supporta la modalita Auto (tutte le risposte come colonne) o Manuale (template JSON personalizzato). Vedi Riferimento Nodi → Completamento per le istruzioni complete di configurazione.

Nodo HTTP

Effettua una richiesta HTTP in uscita come effetto collaterale quando la sessione raggiunge questo nodo. Il colore del nodo e ambra. La richiesta viene eseguita in background; il rispondente non resta in attesa.

Campo	Descrizione
URL	L'endpoint da chiamare.
Metodo	`POST`, `GET`, `PUT`, `PATCH` o `DELETE`.
Body	Corpo JSON inviato con la richiesta. Puoi fare riferimento alle risposte della sessione usando la sintassi delle variabili.

Nodo Trigger Flow

Attiva un Workflow Flusso quando la sessione raggiunge questo nodo. Il colore del nodo e viola. Usalo per trasferire i dati raccolti durante il questionario in un workflow di automazione completo.

Campo	Descrizione
ID Workflow	L'ID del workflow Flusso da attivare.
Mappatura Payload	Mappa le chiavi delle risposte del questionario alle variabili di input del workflow. Ogni riga di mappatura e chiave risposta → nome variabile workflow.

Nodo Webhook

Invia una notifica webhook a un URL esterno quando la sessione raggiunge questo nodo. Il colore del nodo e rosa.

Campo	Descrizione
URL Webhook	L'URL di destinazione per la richiesta POST.
Payload	Corpo JSON da inviare. Puo includere le risposte della sessione tramite la sintassi delle variabili.

Configurazione AI

Clicca il pulsante AI nella barra superiore dell'editor per aprire il pannello Configurazione AI. Questo pannello controlla quale provider AI viene utilizzato per la classificazione delle risposte su tutti i canali (WhatsApp e Chiamata Vocale).

Campo	Descrizione
Provider AI	Seleziona quale provider AI utilizzare per interpretare le risposte a testo libero. Scegli qualsiasi provider configurato in Impostazioni → Provider AI. Seleziona "Usa predefinito account" per utilizzare il provider predefinito.
Prompt del Classificatore	Template di prompt personalizzato opzionale per la classificazione delle risposte. Utilizza i segnaposto `{{options}}` e `{{reply}}`. Lascia vuoto per usare il predefinito integrato. Clicca "Ripristina predefinito" per ripristinare il prompt originale.

Configurazione condivisa: Il provider AI impostato qui viene utilizzato da tutti i canali. Ogni canale (WhatsApp, Chiamata Vocale) utilizza questo provider per interpretare le risposte dei rispondenti. Il canale Chiamata Vocale puo opzionalmente sovrascriverlo con un proprio provider.

Pannello Configurazione AI — selettore del Provider AI e editor del prompt di classificazione. Questa configurazione è condivisa tra tutti i canali.

Incorporamento Web

Puoi incorporare un questionario in qualsiasi pagina web utilizzando un piccolo snippet JavaScript. Il questionario deve essere Attivo affinche l'incorporamento funzioni.

Apri il pannello Incorpora Nella barra superiore dell'editor, clicca </> Incorpora.
Copia lo snippet Il pannello mostra uno snippet HTML. Copialo.
Incolla nella tua pagina Aggiungi lo snippet a qualsiasi pagina HTML dove vuoi che appaia il questionario.

Lo snippet di incorporamento appare cosi:

<div id="flusso-questionnaire"></div> <script src="https://your-flusso-instance.com/embed/questionnaire.js" data-token="YOUR_PUBLIC_TOKEN" data-target="#flusso-questionnaire"> </script>

Suggerimento: Il data-token e il token pubblico del questionario. E sicuro esporlo nel codice HTML lato client — concede solo l'accesso per inviare risposte, non per leggere o modificare la definizione del questionario.

Pannello incorporamento questionario — Pannello Incorpora — mostra lo snippet HTML e il token pubblico. Il questionario deve essere Attivo prima che l'incorporamento sia attivo.

Distribuzione WhatsApp

Clicca il pulsante WhatsApp nella barra superiore dell'editor per aprire il pannello di configurazione WhatsApp. Flusso supporta tre provider di distribuzione:

Pannello configurazione WhatsApp — Pannello WhatsApp — schede per Twilio, OpenClaw e Baileys (self-hosted).

Twilio

Utilizza l'API WhatsApp di Twilio per la distribuzione gestita. Twilio gestisce il provisioning dei numeri di telefono e l'instradamento dei messaggi.

Campo	Descrizione
Account SID	Il tuo Account SID Twilio dalla console Twilio.
Auth Token	Il tuo Auth Token Twilio.
Numero Mittente	Il numero di telefono Twilio abilitato per WhatsApp in formato E.164 (es. `+14155238886`).
URL Webhook Twilio	Generato da Flusso. Copia questo URL e incollalo nel campo webhook Messaging nella tua console Twilio per il Numero Mittente.

Configurazione Twilio: Dopo aver salvato la configurazione Twilio in Flusso, vai nella tua console Twilio, apri la tua WhatsApp Sandbox (o numero approvato) e imposta l'URL webhook When a message comes in sul valore mostrato nel campo URL Webhook Twilio.

OpenClaw

OpenClaw e un gateway che instrada i messaggi WhatsApp verso Flusso tramite un protocollo basato su skill.

Campo	Descrizione
URL Gateway	L'URL della tua istanza gateway OpenClaw.
Skill Bearer Secret	Il secret bearer utilizzato per autenticare le richieste tra OpenClaw e Flusso.
Contenuto SKILL.md	Generato da Flusso. Copialo e configuralo nella definizione skill della tua istanza OpenClaw.
Pannello messaggio di test	Invia un messaggio di test per verificare la connessione prima di andare in produzione.

Baileys (Self-Hosted)

Baileys e un gateway WhatsApp self-hosted che utilizza l'integrazione Account WhatsApp di Flusso. A differenza di Twilio e OpenClaw, Baileys connette direttamente un account WhatsApp reale — non e necessario un account API di terze parti.

Campo	Descrizione
Account WhatsApp	Seleziona un account connesso dal menu a tendina. Gli account sono gestiti in Impostazioni → Account WhatsApp. Solo gli account con stato connesso appaiono qui.

Connetti un Account WhatsApp Vai su Impostazioni → Account WhatsApp e associa un account WhatsApp. Attendi che lo stato diventi connesso.
Seleziona l'account nel pannello Torna nell'editor del questionario, apri il pannello WhatsApp, scegli la scheda Baileys e seleziona l'account connesso dal menu a tendina.
Clicca "Salva Link Baileys" Il questionario e ora collegato a quell'account WhatsApp. I messaggi in arrivo a quel numero verranno instradati attraverso questo questionario.

Un questionario per account: Ogni account WhatsApp puo essere collegato a un solo questionario alla volta. Collegare un account a un nuovo questionario rimuove il collegamento da quello precedente.

Chiamata Vocale AI

Il canale Chiamata Vocale AI ti permette di condurre questionari al telefono. Flusso utilizza Twilio ConversationRelay per effettuare chiamate in uscita in cui un agente AI pone ogni domanda, ascolta le risposte vocali e avanza attraverso il questionario automaticamente.

Come funziona: Twilio gestisce la telefonata, la conversione voce-testo e testo-voce. Il tuo provider AI interpreta le risposte vocali del chiamante e le mappa alle opzioni valide del questionario. Il flusso del questionario resta autoritativo — l'AI non puo saltare o inventare domande.

Clicca il pulsante Chiamata Vocale nella barra superiore dell'editor per aprire il pannello di configurazione. Il pannello e organizzato in sezioni espandibili:

Stato del Canale

Una barra di stato in alto mostra se il canale vocale e attivo o disabilitato. Usa l'interruttore per abilitare o disabilitare il canale. Il questionario deve anche essere Attivo affinche le chiamate funzionino.

Connessione Twilio

Connetti il tuo account Twilio per effettuare chiamate in uscita. Ti serve un account Twilio con un numero di telefono abilitato per le chiamate vocali.

Campo	Descrizione
Account SID	Il tuo Account SID Twilio (inizia con `AC`). Si trova nella dashboard della Console Twilio.
Auth Token	Il tuo Auth Token Twilio. Memorizzato in forma crittografata. Lascia vuoto durante la modifica per mantenere il token esistente.
ID Chiamante	Il numero di telefono Twilio da cui chiamare, in formato E.164 (es. `+15551234567`).
Paese Predefinito	Codice paese predefinito per le chiamate in uscita. Usa il menu a tendina con ricerca e bandiere dei paesi per selezionare.

Modello AI

Scegli quale provider AI interpreta le risposte vocali durante la chiamata. Questo puo sovrascrivere il provider AI a livello di questionario impostato nel pannello Configurazione AI.

Campo	Descrizione
Provider	Seleziona un provider AI, oppure "Usa predefinito questionario" per ereditare dalla Configurazione AI.
Override modello	Usa un modello diverso dal predefinito del provider (es. `gpt-4o-mini` per risposte piu rapide).
Preset vocale	Identificatore vocale opzionale per il provider AI (uso futuro).

Voce e Lingua

Configura la lingua, le impostazioni TTS (text-to-speech) e STT (speech-to-text) per la chiamata.

Campo	Descrizione
Lingua	La lingua per il riconoscimento vocale e la sintesi. Supporta Inglese, Spagnolo, Francese, Italiano, Tedesco, Portoghese, Giapponese, Coreano e Cinese.
Modello vocale	Il modello STT ottimizzato per il tipo di chiamata: `Telephony` (consigliato), `Phone Call` o `Default`.
Text-to-Speech	Seleziona il provider TTS (Google, Amazon o Microsoft) e inserisci un ID voce specifico (es. `en-US-Neural2-F`).
Speech-to-Text	Seleziona il provider di trascrizione: Google o Deepgram.

Comportamento della Chiamata Avanzato

Regola il comportamento dell'agente AI durante la chiamata. Questa sezione e compressa per impostazione predefinita.

Campo	Descrizione
Consenti interruzione	Quando abilitato, il chiamante puo parlare mentre l'AI sta parlando e l'AI si ferma per ascoltare. Consigliato per conversazioni naturali.
Sensibilita interruzione	Quanto facilmente il parlato del chiamante interrompe l'AI: `Bassa`, `Media` o `Alta`. Visibile solo quando l'interruzione e abilitata.
Tentativi massimi	Quante volte l'AI chiedera chiarimenti prima di applicare il comportamento di fallback (0–5).
Timeout silenzio	Secondi di attesa per la risposta del chiamante prima di riproporre la domanda (5–120 secondi).
Quando il chiamante non riesce a rispondere	Cosa succede dopo i tentativi massimi: Leggi tutte le scelte, Riformula la domanda, Salta e prosegui o Termina la chiamata.

Dati e Privacy

Controlla la memorizzazione e la conservazione delle trascrizioni. Questa sezione e compressa per impostazione predefinita.

Campo	Descrizione
Salva trascrizioni	Quando abilitato, la trascrizione completa della chiamata (discorso dell'agente e del chiamante) viene memorizzata per la revisione.
Eliminazione automatica dopo	Numero di giorni prima che le trascrizioni memorizzate vengano eliminate automaticamente (1–365). Visibile solo quando le trascrizioni sono abilitate.

Costi Twilio: Ogni chiamata in uscita comporta costi vocali Twilio piu costi STT e TTS dai provider selezionati. Monitora la dashboard di fatturazione Twilio per tenere traccia dell'utilizzo.

Parlato generato dall'AI: Quando un provider AI e configurato, l'agente vocale genera un parlato naturale e conversazionale invece di leggere modelli rigidi. Aggiunge brevi riscontri tra le domande ("Capito.", "Ottimo, grazie.") e formula le domande in modo piu naturale. Se l'AI non e disponibile, passa automaticamente al parlato basato su template.

Pannello configurazione Chiamata Vocale AI — Pannello Chiamata Vocale — sezioni comprimibili per connessione Twilio, modello AI, impostazioni vocali, comportamento della chiamata e privacy dei dati.

Visualizzazione Risposte

La colonna Risposte nella pagina elenco dei Questionari mostra il numero totale di sessioni create per ogni questionario. Ogni volta che un rispondente apre l'incorporamento web, invia un primo messaggio tramite WhatsApp o riceve una chiamata vocale, viene creata una nuova sessione e il conteggio si incrementa.

Suggerimento: Per distinguere le sessioni completate da quelle abbandonate, usa un nodo Completamento con un nodo Trigger Flow subito prima — il trigger del workflow si attiva solo quando il rispondente raggiunge la fine del grafo, dandoti un segnale affidabile di completamento nella cronologia delle esecuzioni del workflow.