Incorporare un widget di chat sulla base di conoscenza con lead capture

Trasformate la documentazione in un assistente sulla porta d'ingresso

La vostra base di conoscenza contiene già le risposte che i visitatori cercano. Un widget di chat incorporato mette quelle risposte sul vostro sito web come porta d'ingresso conversazionale: i visitatori fanno domande, il widget esegue la stessa pipeline RAG ibrida e la stessa infrastruttura di agente usata dai vostri team interni, e le risposte arrivano con citazioni dai workspace che scegliete di esporre. Questo tutorial percorre l'incorporamento del widget, il controllo su cosa risponde, la cattura dei lead e la corretta configurazione di CORS - dal pannello di amministrazione a uno snippet funzionante in pochi minuti.

L'incorporamento in due passi: un loader e un iframe sandbox

Il widget è costruito attorno a un pattern di incorporamento orientato alla sicurezza. Invece di iniettare markup e stili nella vostra pagina, il widget arriva in due passi:

1. Lo script loader. Aggiungete un solo tag script al sito, puntato al vostro servizio widget con l'ID del widget. Il loader è un piccolo file JavaScript che crea un iframe nella pagina ospite.
2. Il pannello iframe. L'iframe carica un'applicazione Preact autosufficiente - compilata come bundle IIFE con CSS inlinato - che disegna il pulsante flottante, il pannello di chat e ogni interazione dentro il proprio documento.

<script src="https://il-vostro-simmetric-chat.com/widget/loader.js?widgetId=WIDGET_ID"></script>

Perché un iframe? Perché l'interpolazione di stringhe di contenuto non fidato dentro una pagina ospite è la via classica dell'XSS. Far girare l'interfaccia del widget dentro un iframe sandbox a origine opaca elimina del tutto quella classe di rischio: il contenuto della chat non viene mai eseguito nel contesto della vostra pagina. Le vecchie rotte di incorporamento a interpolazione di stringhe sono state rimosse dal prodotto esattamente per questa ragione, quindi il pattern in due passi non è un'opzione tra molte - è l'incorporamento.

La comunicazione tra iframe e pagina avviene attraverso un piccolo protocollo postMessage versionato (tipi di messaggio simmetric:*) che gestisce il balletto di apertura/chiusura del FAB, il ricoloro del FAB e gli handshake dello storage di sessione. Entrambi i lati validano ogni messaggio in entrata contro l'esatto contentWindow atteso, così che i messaggi contraffatti tra iframe diversi vengano ignorati.

Creare il widget e puntarlo alla conoscenza

Tutto inizia nel pannello di amministrazione:

1. Create un widget da Impostazioni → Widget. La creazione è vincolata alla licenza (widget_enabled) e rispetta il limite numerico di widget del piano.
2. Collegate il widget a uno o più workspace. La whitelist dei workspace sostituisce atomicamente tutti i collegamenti precedenti, quindi stratificare l'accesso alla base di conoscenza è una questione di quali workspace allegare.
3. Configurate il branding: colore primario, nome del bot, loghi, posizione (in basso a destra o in basso a sinistra). I deployment tier Community ricevono valori predefiniti sensati quando i campi sono vuoti; la personalizzazione completa e il white-labeling sono flag enterprise.
4. Copiate lo snippet di incorporamento nell'HTML del sito.

Poiché i widget sono definiti per workspace, la conoscenza su cui un widget può attingere è esattamente l'unione delle basi di conoscenza dei workspace collegati - niente di più. Un widget di supporto può vedere il workspace della documentazione pubblica senza mai toccare i dati dei progetti interni.

Il model pin delle risposte: risolto lato server

Un'aggiunta recente conta per il controllo di qualità: la configurazione di ogni widget può selezionare uno specifico provider e modello LLM che serve le risposte della chat di quel widget. Il pin è conservato sulla riga del widget e risolto lato server a ogni richiesta di chat - non è mai fornito dal client, dal proxy del widget o dal browser del visitatore. Un modello ancorato ha priorità sul default del workspace, e i widget senza pin mantengono la catena di risoluzione standard. In pratica: il vostro widget di marketing può girare sull'esatto modello che avete verificato per le risposte pubbliche, indipendentemente da ciò che chiunque manometta lato client.

Lead capture che rispetta i visitatori

Il lead capture del widget è progettato per la realtà di un modulo pubblico: gli abusi si concentrano dove i dati vengono raccolti, quindi l'endpoint dei lead è volutamente limitato a 3 richieste l'ora per sorgente (con il limite reso visibile all'utente). Il flusso:

• Il visitatore vede una barriera di consenso sulle informazioni personali prima di chattare - un riconoscimento esplicito di come i dati sono trattati, non un link a una politica nascosto in fondo.
• Una scheda lead raccoglie i dati di contatto durante o dopo la conversazione, e gli invii finiscono nella casella dei lead del widget nel pannello di amministrazione, con esportazione CSV per la vostra pipeline.
• Le sessioni sono anonime per scelta di progettazione: il server crea una sessione con un token a 256 bit e una scadenza di 24 ore, e ogni richiesta successiva viene validata contro di essa. I limiti per sessione (20 messaggi l'ora, 5 conversazioni al giorno) restituiscono un 429 con un suggerimento retryAfter quando superati, e l'interfaccia mostra un avviso di rate limit anziché fallire in silenzio.

I rate limit fanno parte della storia di fiducia, non un ripensamento: una superficie di chat pubblica dovrebbe degradare con garbo sotto carico o abuso, e il limitatore dei lead è la barriera più stretta dei tre limitatori lato widget.

CORS: chiuso per difetto per impostazione predefinita

Il traffico dei widget attraversa origini per definizione, quindi CORS fa parte della superficie di sicurezza anziché essere un ripensamento. Ogni widget porta la propria lista allowedOrigins, modificabile dal pannello di amministrazione. A runtime, un middleware CORS dinamico valida l'header Origin di ogni richiesta contro la lista di quel widget - le richieste da origini non consentite vengono respinte al preflight, e il middleware fallisce chiuso: se il controllo dell'origine non può consultare il database, l'accesso è negato anziché concesso.

Configuratelo in un solo passaggio:

• Aggiungete le origini del vostro sito (schema e host, senza giochi con la barra finale) alle origini consentite del widget.
• Ricordate che le varianti di sottodominio contano come origini distinte - esempio.com e www.esempio.com sono due voci.
• Usate origini https:// in produzione; il servizio widget parla le stesse regole URL del resto dello stack.

Tutto il resto - l'URL del loader, l'iframe, il bootstrap della sessione, lo stream SSE della chat - usa lo stesso host su cui distribuite il servizio widget, quindi c'è esattamente un luogo dove la fiducia di origine viene decisa: la lista consentita del widget.

Cosa gira dove

Una rapida mappa di orientamento, perché il widget tocca tre processi:

• Server principale - CRUD dei widget e branding, collegamento dei workspace, l'API interna che il servizio widget chiama con la sua API key, ed endpoint lead/analytics per gli amministratori. L'intero router interno restituisce 402 quando la funzionalità widget è spenta.
• Servizio widget - la superficie pubblica di incorporamento: loader JS, HTML dell'iframe, creazione delle sessioni, consegna della configurazione in cache, il proxy SSE della chat verso il server principale e l'endpoint dei lead. Si autentica presso il server principale con una WIDGET_API_KEY e porta i propri limitatori di frequenza.
• L'iframe - il client Preact IIFE con il ciclo di vita della chat: creazione della sessione, streaming SSE token per token, visualizzazione delle citazioni, domande suggerite e barriere di consenso.

Il proxy della chat inoltra lo stesso formato di evento dell'API di streaming interna - messaggi di stato, annunci del piano, token in streaming, citazioni ed eventi terminali done/error - così che tutto ciò che la vostra squadra vede in una chat di workspace, i vostri visitatori lo sperimentano nel widget.

Lista di controllo per il lancio

• Widget creato, funzionalità della licenza attiva, workspace collegati
• Branding impostato; flag white-label se il widget non deve portare il marchio del prodotto
• Model pin delle risposte impostato sulla riga del widget (risolto lato server)
• Origini consentite che coprono ogni sito e sottodominio che lo incorporerà
• Lead capture verificato end-to-end: barriera di consenso, invio, casella admin, esportazione CSV
• Rate limit compresi: 3 lead/ora, 20 messaggi/ora per sessione, 5 conversazioni/giorno

Da lì, il widget è un drop-in: un tag script, una lista consentita, una base di conoscenza di cui già vi fidate. Quando i vostri visitatori fanno domande, ottengono risposte fondate esattamente sui workspace che avete scelto - con una pipeline di lead capture che è cortese con gli esseri umani e severa con i bot.

Leggi la guida completa nella documentazione →