Un assistente WhatsApp per un broker assicurativo che risponde solo quando trova la risposta nei documenti

Il contesto

Il cliente è un broker assicurativo che lavora con 18 compagnie. I suoi clienti scrivono su WhatsApp per chiedere cosa copre una polizza o come funziona un prodotto, e a queste chat rispondono le persone dell'ufficio. L'obiettivo del progetto è un assistente che risponda da solo alle domande sui prodotti e passi agli operatori tutto il resto.

Il progetto è a due mani, ed è giusto dirlo subito. Il motore del bot, cioè l'agente che conversa, la ricezione dei messaggi, la verifica dell'identità del cliente e il portale degli operatori, è di uno sviluppatore esterno, con un codice suo. Io ho costruito la base di conoscenza e la ricerca sui documenti, gli avvisi agli operatori, la persona del bot (le istruzioni su tono e regole), i test, e ho proposto la scelta del modello. Le modifiche al motore le propongo allo sviluppatore, che le valuta e le integra.

Il problema

Il primo problema era il materiale. I documenti delle compagnie erano 4.936 file, 4,4 GB, di 46 compagnie diverse. Dentro c'era di tutto: fascicoli in vigore, versioni superate e documenti interni come norme assuntive e tariffe, che un cliente non deve mai ricevere. Dare tutto in pasto a un bot voleva dire rischiare risposte basate su un prodotto non più in vendita o su un documento riservato.

Il secondo problema è emerso nelle prove. Al 7 ottobre il bot, con un modello economico, rispondeva tre volte in 16 secondi a tre messaggi ravvicinati, dava risposte in contraddizione fra loro e ignorava regole già scritte nelle istruzioni: nominava al cliente gli strumenti interni e, invece di passare la chat a un operatore, rispondeva in modo vago pescando dai documenti. Misurato su 62 chat reali, il punteggio di qualità era 2,24 su 5.

Per un broker una risposta sbagliata su una copertura non è un fastidio: è un cliente che crede di essere assicurato per qualcosa che il contratto non prevede.

Cosa ho costruito

Ho tenuto la base di conoscenza su un'infrastruttura mia, separata dal database del bot: n8n su un server dedicato, un database Postgres con ricerca vettoriale, i PDF serviti da un file server. Così la parte che conosce i prodotti non dipende dal codice dello sviluppatore esterno e si aggiorna senza toccarlo.

1. Arriva il messaggio. Meta manda l'evento a n8n, che lo inoltra al motore del bot identico, byte per byte, perché la firma di Meta resti valida.
2. Il bot cerca. Se la domanda riguarda un prodotto, il bot chiama la mia ricerca come uno strumento.
3. La ricerca filtra. Cerca per significato nei documenti; se nessun passaggio supera una soglia di somiglianza, restituisce un risultato vuoto. Meglio nessuna risposta che una inventata.
4. L'operatore viene avvisato. Ogni 10 minuti, dalle 8 alle 20, un'automazione manda al titolare un'email e un messaggio WhatsApp con le chat da prendere in carico.
5. Tutto viene registrato. Ogni ricerca finisce in un registro con i dati personali mascherati, per ritarare la soglia su domande vere.

La scelta più importante è stata cosa mettere dentro. Ho tenuto solo le 18 compagnie trattate e solo i documenti in vigore e consegnabili al cliente: 225 documenti, divisi in 23.406 blocchi di testo. La soglia l'ho scelta con un set di prova di 39 domande, in parte sui prodotti e in parte volutamente fuori tema. Ho provato anche una ricerca per parole chiave e l'ho tolta: non separava le domande buone da quelle fuori tema.

Poi istruzioni e modello. Ho riscritto la persona del bot e ho preparato un test a chat intere: 62 conversazioni reali aperte dai clienti fra il 16 settembre e il 20 ottobre, rigiocate con configurazioni diverse e valutate da un giudice AI. Il test ha mostrato una cosa che non mi aspettavo. Con le istruzioni nuove il modello economico passava solo da 2,24 a 2,57: il problema non era il testo, era il modello. Con un modello più capace, e più caro per singola risposta, le stesse istruzioni arrivavano a 4,05. Il 20 ottobre sono andati in linea istruzioni e modello nuovi, il 21 ottobre il registro formale, con il Lei.

I risultati

I numeri qui sotto vengono da valutazioni fatte in prova, non dall'esercizio con tutti i clienti. Misurano due cose diverse: quanto la ricerca trova il documento giusto, e quanto le risposte complete del bot sono corrette e rispettano le regole. Il dato meno bello è il 17 su 27: in 10 domande la ricerca restituisce testo pertinente ma non il passaggio esatto. È il motivo per cui le istruzioni chiedono al bot di passare la chat a un operatore quando i documenti non rispondono in modo chiaro.

Cosa rifarei diversamente

Ho passato giorni a riscrivere le istruzioni per correggere comportamenti che il modello semplicemente non seguiva. Le regole c'erano già: non nominare gli strumenti, passare all'operatore quando il documento non risponde. Il modello economico le ignorava. Oggi parto dal test a chat intere su conversazioni vere, provo due o tre modelli con le stesse istruzioni e solo dopo lavoro sul testo. Costa un giorno e ne risparmia parecchi.

La seconda lezione riguarda il lavoro a due. Alcuni difetti si vedono nella chat ma stanno nel motore, non nella mia parte: il raggruppamento dei messaggi ravvicinati, chiesto il 7 ottobre, al 21 ottobre non c'era ancora. Rifarei subito un elenco condiviso dei difetti, con chi li corregge e una data, invece di segnalarli man mano.

Per chi ha senso

Ha senso per chi riceve su WhatsApp molte domande su prodotti descritti in documenti lunghi: broker e agenzie, ma anche chi vende servizi tecnici o finanziari con condizioni scritte. Il requisito è avere i documenti in ordine, o la pazienza di metterli in ordine prima.

Non serve se le domande sono poche, o se ogni risposta richiede di guardare la posizione del singolo cliente: lì un buon sistema di avvisi all'operatore vale più di un bot.

Strumenti usati

n8nWhatsApp Cloud APIPostgres con pgvectorOpenRouterEasypanel

Numeri letti dai report di valutazione del progetto (set di prova del 23 settembre 2026, test su chat reali del 20 ottobre 2026, prova del 21 ottobre 2026), senza modificarli.