Developer Docs

Pathfinder — Sistema di Navigazione Guidata

Pathfinder è il modulo PROMIUM per la creazione di flussi conversazionali strutturati a step. Guida l'utente attraverso percorsi predefiniti di domande e risposte, ottimizzando la qualifica lead, l'assistenza tecnica e i processi di onboarding.

Prodotto: PROMIUM ASSISTANT + WEB CONTACT Setup: ~30 minuti Tipo: Flussi JSON configurabili

Cos'è Pathfinder

A differenza del chatbot libero basato su RAG, Pathfinder implementa un sistema di navigazione guidata a nodi in cui ogni step presenta all'utente un set di opzioni predefinite. L'utente procede nel flusso tramite selezioni, non testo libero.

Chatbot RAG libero
L'utente scrive testo libero → l'AI risponde attingendo alla knowledge base. Ideale per support generale.

Pathfinder guidato
L'utente seleziona tra opzioni → il flusso lo guida verso la soluzione o l'azione. Ideale per qualifica, acquisto, troubleshooting.

Casi d'uso tipici

Qualifica lead: guida il prospect attraverso domande BANT e prenota un appuntamento
Troubleshooting tecnico: albero decisionale per diagnosi problemi prodotto step-by-step
Onboarding neoassunti: percorso guidato per completare le attività del primo giorno
Configuratore prodotto: guida l'utente alla scelta del prodotto/piano giusto
Richiesta preventivo: raccolta dati strutturata prima di passare al commerciale
Segnalazione problemi: categorizzazione automatica ticket con tutti i dati necessari

Struttura di un flusso Pathfinder

Un flusso Pathfinder è definito in formato JSON come un grafo orientato di nodi. Ogni nodo ha un id, un type, un messaggio e opzioni di navigazione verso nodi successivi.

{
  "id": "qualifica-lead-v1",
  "name": "Qualifica Lead B2B",
  "lang": "it",
  "startNode": "benvenuto",
  "nodes": [
    {
      "id": "benvenuto",
      "type": "message",
      "text": "👋 Ciao! Sono l'assistente PROMIUM. Come posso aiutarti oggi?",
      "options": [
        { "label": "Voglio una demo",      "next": "info-azienda" },
        { "label": "Ho un problema",       "next": "supporto" },
        { "label": "Voglio informazioni",  "next": "info-prodotti" }
      ]
    },
    {
      "id": "info-azienda",
      "type": "input",
      "inputType": "text",
      "text": "Ottimo! Come si chiama la tua azienda?",
      "field": "company_name",
      "next": "dimensione"
    },
    {
      "id": "dimensione",
      "type": "message",
      "text": "Quanti dipendenti ha la tua azienda?",
      "options": [
        { "label": "1–10",    "next": "email", "tag": "micro" },
        { "label": "11–50",   "next": "email", "tag": "sme" },
        { "label": "51–200",  "next": "email", "tag": "mid" },
        { "label": "200+",    "next": "email", "tag": "enterprise" }
      ]
    },
    {
      "id": "email",
      "type": "input",
      "inputType": "email",
      "text": "Perfetto! Inserisci la tua email aziendale per ricevere i dettagli:",
      "field": "email",
      "validation": "email",
      "next": "fine"
    },
    {
      "id": "fine",
      "type": "end",
      "text": "✅ Grazie! Un nostro specialista ti contatterà entro 24 ore.",
      "action": "submit_lead"
    }
  ]
}

Tipi di nodo disponibili

Tipo (`type`)	Descrizione	Proprietà aggiuntive
`message`	Nodo con messaggio testuale e pulsanti di scelta.	`options[]`: array di etichette + nodo successivo
`input`	Nodo che raccoglie un input testuale dall'utente.	`inputType`: text / email / tel / number `field`: nome variabile da salvare `validation`: regola di validazione
`media`	Nodo che mostra immagine, video o PDF prima di procedere.	`mediaUrl`, `mediaType`: image/video/pdf
`condition`	Nodo di branch condizionale basato su variabili precedenti.	`conditions[]`: regole `if/then/else`
`api`	Nodo che chiama un endpoint REST esterno e usa la risposta.	`endpoint`, `method`, `mapping`
`end`	Nodo terminale: chiude il flusso ed esegue un'azione.	`action`: submit_lead / open_url / book_meeting / webhook

Embed del flusso Pathfinder

Per abilitare Pathfinder su un bot esistente, aggiungi il parametro data-pathfinder-flow con l'ID del flusso configurato nella dashboard:

<script
  src="https://cdn.promiumai.com/widget/v2/promium-chat.min.js"
  data-bot-id="YOUR_BOT_ID"
  data-pathfinder-flow="qualifica-lead-v1"
  data-pathfinder-trigger="auto"
  async
></script>

Parametro	Valori	Descrizione
`data-pathfinder-flow`	string (ID flusso)	ID del flusso Pathfinder da avviare.
`data-pathfinder-trigger`	`auto` / `manual` / `exit-intent`	`auto`: parte subito · `manual`: avviato da JS · `exit-intent`: si attiva all'uscita dalla pagina
`data-pathfinder-delay`	number (ms)	Ritardo prima dell'avvio automatico del flusso.

Vuoi creare un flusso personalizzato?
Il team PROMIUM progetta Pathfinder flow su misura per il tuo business. Parla con noi →