Modulo di Contatto in Chat (HITL)

Il modulo di contatto permette all'assistente AI di raccogliere dati dell'utente direttamente nella chat, con un flusso Human-in-the-Loop (HITL) basato su interrupt() di LangGraph.

Panoramica

1. L'agente invoca il tool requestContactForm quando l'utente chiede un preventivo, un callback o vuole lasciare i propri dati.
2. Il Node Agent interrompe il grafo LangGraph e invia al widget l'evento Socket.IO contact_form_request con un openToken firmato (HMAC).
3. Il widget mostra un overlay con i campi configurati dall'admin.
4. L'utente compila e invia → Laravel valida, persiste la richiesta e invia le email.
5. Il grafo riprende con Command({ resume }) e l'agente riceve solo l'esito (submitted / closed / timeout).

Configurazione Admin

Nella pagina di personalizzazione assistente/agente (resource-customization):

• Abilitazione del modulo di contatto
• Titolo, testo pulsante submit, URL privacy policy (HTTPS obbligatorio se abilitato)
• Destinatari email (uno o più)
• Campi personalizzati: text, email, textarea, select, date, checkbox

Le impostazioni sono salvate in contact_form_settings (JSON) sul modello Assistant o Agent. Solo un sottoinsieme sicuro (renderableSubset) viene esposto al widget bootstrap.

API Laravel

Endpoint	Metodo	Descrizione
/api/embed/contact-form/context/{uuid}	POST	Riceve contesto conversazione dal Node Agent (JWT node)
/api/embed/contact-request/{uuid}	POST	Submit del form dall'utente (throttle + HMAC)
/api/embed/contact-request/erase	DELETE	Cancellazione GDPR per hash
/conversations/{id}/summary	POST	Genera riepilogo conversazione (dashboard)

Modelli e servizi principali

• ContactRequest — richiesta persistita con reference code
• ContactFormContext — contesto conversazione associato
• ContactFormSigningService — firma/verifica HMAC per openToken e receipt
• ContactFormSubmitValidator — validazione campi lato server
• ConversationSummaryService — riepilogo LLM per la dashboard
• SendContactRequestNotifications — job email a destinatari e utente

Comandi schedulati

# Purge dati scaduti (giornaliero alle 03:00)
php artisan contact-form:purge

# Retry email fallite (ogni ora)
php artisan contact-form:sweep-mail

Dashboard

• Sezione Richieste contatto nell'area admin
• Vista dettaglio conversazione con pulsante per generare il riepilogo
• Policy ContactRequestPolicy per controllo accessi

Eventi Socket.IO (widget)

Evento	Direzione	Descrizione
contact_form_request	Server → Client	Apre overlay con requestId, openToken, exp
contact_form_submitted	Client → Server	Invia receipt dopo submit riuscito
contact_form_cancelled	Client → Server	Annullamento utente
contact_form_heartbeat	Client → Server	Reset TTL (timeout 5 minuti)

Vedi anche: Contact Form HITL (Node Agent).