Concetti fondamentali

Prima di configurare qualsiasi cosa, allinea il vocabolario. Ogni concetto qui sotto corrisponde a un oggetto concreto della piattaforma, con una sua schermata in Console e una sua rappresentazione nelle API.

Tenant

Il tenant è la tua organizzazione all'interno della piattaforma. È il confine di isolamento più esterno: utenti, progetti, conversazioni, documenti e fatture appartengono a un tenant e non sono raggiungibili da altri tenant.

Ogni tenant ha uno slug, un identificatore breve in minuscolo usato negli URL, nelle API e nelle e-mail di sistema.

Esempio. Lo studio "Acme S.r.l." (P.IVA IT01234567890) riceve il tenant con slug acme-srl. Le sue conversazioni non sono visibili al poliambulatorio concorrente ospitato sulla stessa piattaforma.

Workspace

Il workspace è la suddivisione interna di un tenant, tipicamente per reparto, sede o linea di business. Serve a separare la visibilità dei dati tra team che lavorano nella stessa azienda.

Esempio. Il tenant acme-srl crea i workspace sede-milano e sede-torino: l'operatore di Torino vede solo le conversazioni della propria sede, mentre la direzione vede entrambe.

Progetto

Il progetto è l'unità di pubblicazione. Raccoglie agente, modello AI, avatar, flussi conversazionali, data store collegati, domini autorizzati e chiavi di accesso. Un widget pubblicato corrisponde sempre a un progetto.

Ogni progetto espone una chiave nel formato bp_proj_xxxxxxxxxxxxxxxx.

Esempio. acme-srl crea il progetto "Assistenza clienti sito pubblico" (bp_proj_7f3a9c21) e un secondo progetto "Portale riservato rivenditori", con knowledge base diversa e regole di accesso più restrittive.

Agente

L'agente è la personalità operativa che risponde: prompt di sistema, tono di voce, ambito di competenza, strumenti che può invocare, condizioni di passaggio a un operatore umano. È l'agente a decidere come rispondere; il modello AI fornisce solo la capacità linguistica.

Esempio. L'agente "Segreteria" risponde solo su orari, sedi e modalità di prenotazione; se la domanda riguarda un referto, chiede l'intervento di un operatore.

Modello AI

Il modello AI è il motore linguistico selezionato dal catalogo, con i suoi parametri: temperatura, numero massimo di token, finestra di contesto ed eventuale modello di fallback usato quando il principale non è disponibile.

Esempio. Modello principale con temperatura 0.2 per risposte deterministiche su procedure amministrative; fallback su un modello più economico per gestire i picchi di traffico.

Sessione e conversazione

La sessione è il contesto tecnico aperto quando un visitatore avvia la chat: identificativo, progetto, lingua, pagina di origine, metadati. La conversazione è lo scambio di messaggi che avviene dentro quella sessione.

Una sessione può contenere più turni, cambiare stato (attiva, in attesa di operatore, presa in carico, chiusa) e viene conservata per il periodo di retention del piano.

Esempio. Mario Rossi apre la chat dalla pagina "Contatti" alle 09:14, scrive tre messaggi, viene servito dall'agente e chiude alle 09:19: una sessione, sei messaggi.

Handover

L'handover è il passaggio della conversazione dall'agente AI a un operatore umano. Può essere automatico (parola chiave, intento non riconosciuto, sentiment negativo, richiesta esplicita) oppure manuale, quando un operatore decide di intervenire da Console.

Dopo l'handover il visitatore continua a scrivere nella stessa finestra: cambia solo chi risponde.

Esempio. Il visitatore scrive "voglio parlare con una persona": la sessione entra in coda, un operatore la prende in carico entro il tempo previsto dalla SLA interna.

Widget

Il widget è l'interfaccia di chat incorporata nel sito, generata dal widget builder e distribuita come script UMD. Ne definisci colori, posizione, messaggio di benvenuto, avatar, lingue e comportamento su mobile.

Esempio. Bolla in basso a destra, colore aziendale, apertura automatica dopo 20 secondi solo sulle pagine di listino.

Data store (knowledge base)

Il data store è l'archivio indicizzato da cui l'agente recupera le informazioni: documenti caricati, pagine web acquisite, sorgenti collegate. I contenuti vengono suddivisi in frammenti e trasformati in vettori per la ricerca semantica.

Esempio. Il data store "Regolamento e listini 2026" contiene il tariffario in PDF, le condizioni generali in DOCX e le FAQ in Markdown.

Strumento (tool)

Lo strumento è una funzione esterna che l'agente può invocare durante la conversazione: consultare disponibilità, creare un ticket, verificare uno stato pratica. Ogni strumento dichiara i parametri di ingresso, l'endpoint da chiamare e il metodo di autenticazione.

Esempio. Lo strumento verifica_disponibilita riceve data e prestazione e restituisce i primi tre slot liberi in agenda.

Webhook

Il webhook è la notifica in uscita: quando accade un evento sulla piattaforma, la piattaforma esegue una richiesta HTTP verso un endpoint che hai registrato, firmata in HMAC per garantirne l'autenticità.

Esempio. All'evento session.handover.requested il gestionale apre automaticamente un'attività assegnata al reparto competente.

Ruolo e permesso

Il permesso è l'autorizzazione elementare, espressa nel formato {servizio}:{risorsa}:{azione}. Il ruolo è un insieme di permessi assegnato a un utente all'interno di un tenant.

identity:users:read       leggere l'anagrafica utenti
identity:users:invite     invitare nuovi utenti
console:sessions:write    rispondere nelle conversazioni
billing:invoices:read     consultare le fatture

Esempio. Il ruolo "Operatore" include console:sessions:read e console:sessions:write, ma non billing:invoices:read.

Chiave API

La chiave API autentica le chiamate applicative server-to-server. Viene mostrata una sola volta alla creazione, è conservata solo come hash e si usa nell'intestazione Authorization.

Esempio. Il gestionale usa bp_live_xxxxxxxxxxxxxxxx per sincronizzare ogni notte l'anagrafica clienti.

Ambiente

L'ambiente determina dove una configurazione è attiva: sviluppo per le prove, staging per la validazione, produzione per il pubblico. Chiavi, domini autorizzati e limiti di traffico sono distinti per ambiente.

Esempio. Il nuovo prompt di sistema viene provato in sviluppo, validato dalla direzione in staging e solo dopo pubblicato in produzione.

Tabella riassuntiva