FIELD NOTES / 01 · VOICE ARCHITECTURE
Dentro un voice bot enterprise
Dalla telefonata ai sistemi aziendali: componenti, conversazione e gestione dei guasti, attraverso la mia esperienza.
In oltre tre anni di lavoro su assistenti vocali enterprise mi sono occupato di sviluppo backend, integrazioni e amministrazione dei database. Ho imparato che la qualità della conversazione dipende anche da ciò che il chiamante non vede: connessioni, tempi di attesa, stato delle operazioni e capacità di ricostruire un errore.
Questa è una mia architettura di riferimento, maturata attraverso quell’esperienza. Voice Gateway, Google STT e TTS, Watson Assistant e un modulo Java Spring verso sistemi raggiungibili tramite VPN sono il punto di partenza. Bilanciamento, archivio delle sessioni, gestione dei segreti, pipeline eventi e percorso operatore completano la proposta: non riproducono il sistema di uno specifico cliente.
Nel modello scelgo una chiamata applicativa da Watson Assistant alle API Spring attraverso un ingresso autenticato. È una scelta progettuale di questa rappresentazione. Il ponte verso Google STT/TTS è mostrato come adapter: protocolli, codec e compatibilità con la versione di Voice Gateway vanno verificati nell’integrazione concreta.
01 / ARCHITETTURA
La struttura dietro la voce
Seleziona un componente per leggere la sua responsabilità. I collegamenti mostrano dipendenze logiche; la sequenza sotto esplicita direzione e ordine dei messaggi.
Verde: nucleo dell’esperienza · Blu: componenti della proposta · Tratteggio: servizi trasversali
Componenti e responsabilità
Caller Chiamante
Una richiesta vocale; identità e autorizzazione sono verificate separatamente.
SBC / SIP Ingresso telefonico
Confine telefonico: instradamento SIP e politiche sul traffico voce. Il percorso media dipende dalla topologia telefonica.
Voice Gateway Sessione e audio
Collega la chiamata alla conversazione e coordina lo scambio audio/testo con i servizi vocali tramite adapter.
Google STT / TTS Adapter voce
STT trascrive l’audio; TTS sintetizza il testo. L’adapter gestisce formati e protocolli; non assumo compatibilità nativa con qualsiasi versione del gateway.
Watson Assistant Dialogo e risposte
Gestisce il turno e usa esiti applicativi strutturati per formulare risposte o proporre un trasferimento.
API ingress / LB Autenticazione e routing
Autentica le richieste applicative e distribuisce il carico alle istanze Spring sane. Endpoint e connettività verso Watson vanno progettati esplicitamente.
Java Spring × N Adapter e resilienza
Esegue la logica applicativa, controlla le autorizzazioni e isola le integrazioni con timeout, bulkhead e circuit breaker. Redis non sostituisce i sistemi autorevoli.
VPN → Systems Sistemi aziendali
Il tunnel protegge il collegamento verso le API esterne. I sistemi restano responsabili dei dati e delle operazioni; servono anche autenticazione e autorizzazione.
Redis / Session Contesto con scadenza
Condivide il contesto temporaneo tra istanze Spring, con TTL e limiti. Le chiavi di idempotenza richiedono durabilità e regole proprie, non solo una cache.
Contact center Operatore e contesto
Riceve la chiamata trasferita e un riferimento al contesto minimo necessario. Disponibilità della coda e fallimenti di trasferimento sono gestiti esplicitamente.
Event queue Eventi asincroni
Disaccoppia la conversazione dalle analisi. Backpressure, retry limitati, deduplicazione e coda degli scarti fanno parte del progetto.
Analytics Consumer → database
Il consumer trasforma gli eventi per report e dashboard in un archivio separato. Nessuna query della dashboard blocca la risposta vocale.
Secrets manager Credenziali e rotazione
Fornisce segreti ai servizi autorizzati, con privilegi minimi e rotazione. Non trasporta il contenuto della conversazione.
Observability Metriche · log · tracce
Collega gli eventi tramite un ID di correlazione. Misura latenza per fase, errori, saturazione dei pool, code e trasferimenti senza registrare contenuti sensibili per default.
02 / IL FLUSSO
Segui una chiamata
Esempio illustrativo: «Qual è lo stato della mia richiesta?». L’utente è già autenticato per l’operazione; il numero chiamante, da solo, non prova l’identità. I tempi della riproduzione sono didattici, non misure di latenza.
Sequence diagram
Leggi dall’alto verso il basso. Freccia continua: richiesta o comando. Tratteggiata: risposta. Arancione: esito degradato. Viola: pubblicazione asincrona. Ingresso API, adapter e VPN sono raggruppati nella corsia Spring → Sistemi; i servizi STT e TTS condividono una corsia.
Diagramma scorrevole orizzontalmente. La sequenza testuale completa è disponibile subito sotto.
Chiamata normale
Sequenza testuale
- Caller → Gateway Chiamata attraverso SBC / SIP
- Gateway → STT / TTS Audio → Google STT
- STT / TTS → Gateway Trascrizione del turno
- Gateway → Watson Testo e contesto del turno
- Watson → Spring Richiesta autenticata via API ingress
- Spring → Systems Lettura stato tramite adapter e VPN
- Systems → Spring Esito applicativo: stato disponibile
- Spring → Watson Risultato strutturato e validato
- Watson → Gateway Testo della risposta
- Gateway → STT / TTS Testo → Google TTS
- STT / TTS → Gateway Audio sintetizzato
- Gateway → Caller Riproduzione della risposta
- Spring → Events Evento minimizzato (asincrono)
Backend lento
Sequenza testuale
- Caller → Gateway Chiamata attraverso SBC / SIP
- Gateway → STT / TTS Audio → Google STT
- STT / TTS → Gateway Trascrizione del turno
- Gateway → Watson Testo e contesto del turno
- Watson → Spring Richiesta autenticata via API ingress
- Spring → Systems Lettura stato tramite adapter e VPN
- Systems → Spring Timeout: risultato non disponibile
- Spring → Watson Esito degradato; nessun successo inventato
- Watson → Gateway Spiega il problema e offre alternative
- Gateway → STT / TTS Sintesi del messaggio di fallback
- STT / TTS → Gateway Audio sintetizzato
- Gateway → Caller Messaggio utile entro il budget
- Spring → Events Evento timeout (asincrono)
Passaggio a un operatore
Sequenza testuale
- Caller → Gateway Chiamata attraverso SBC / SIP
- Gateway → STT / TTS Audio → Google STT
- STT / TTS → Gateway Trascrizione del turno
- Gateway → Watson Testo e contesto del turno
- Watson → Spring Prepara contesto minimo per operatore
- Spring → Operator Consegna contesto al contact center
- Operator → Spring Riferimento al contesto ricevuto
- Spring → Watson Riferimento pronto per il trasferimento
- Watson → Gateway Richiede trasferimento concordato
- Gateway → Operator Trasferimento telefonico via SBC
- Operator → Caller Conversazione con operatore disponibile
- Spring → Events Evento handoff (asincrono)
Gli eventi sono mostrati in fondo per leggibilità: non dipendono dall’attesa della riproduzione audio. Il trasferimento rappresenta il percorso riuscito; se l’operatore non è disponibile si propone un’alternativa. Un circuito già aperto può rifiutare la richiesta prima di raggiungere i sistemi.
03 / SCELTE E COMPROMESSI
Le decisioni che rendono utile il modello
Il budget di attesa appartiene alla conversazione
Definirei un budget complessivo per il turno, distribuendolo tra riconoscimento, dialogo, chiamate applicative e sintesi. Il timeout del singolo servizio deve lasciare tempo per una risposta utile. Le soglie si scelgono misurando il percorso reale, non copiando un valore universale. Se scade l’attesa, Watson riceve un esito esplicito: non un dato vuoto interpretato come successo.
Un guasto non deve occupare tutte le risorse
Nel modulo Spring gli adapter separano i client verso ciascun sistema. Timeout limitano l’attesa; bulkhead e pool limitati contengono la concorrenza; circuit breaker sospendono le chiamate quando le soglie configurate indicano un guasto persistente. Un singolo timeout non apre necessariamente il circuito. Per operazioni con effetti, un retry richiede idempotenza e riconciliazione dell’esito: il timeout non significa che l’operazione non sia avvenuta.
Scalare Spring non salva automaticamente la telefonata
Il bilanciatore può distribuire nuove richieste tra istanze sane; Redis può condividere il contesto applicativo con una scadenza. Nessuno dei due recupera da solo una sessione audio interrotta. Telefonia, gateway, VPN e archivi richiedono strategie di disponibilità e prove di failover proprie. Anche Redis e la coda possono diventare punti di guasto: servono limiti e comportamenti espliciti quando non rispondono.
Analytics fuori dal tempo di risposta
Il modulo pubblica eventi minimizzati su una coda; un consumer alimenta il database analytics. Il chiamante non attende la dashboard. I consumer devono gestire duplicati, ritardi e messaggi non elaborabili, con retry limitati e una coda degli scarti. Se un evento deve essere garantito insieme a una modifica persistente, valuterei un outbox transazionale; per telemetria non critica è possibile una consegna best effort dichiarata.
La VPN non sostituisce i controlli applicativi
L’ingresso API autentica Watson e applica limiti; Spring verifica le autorizzazioni dell’utente prima di interrogare i sistemi. Un gestore di segreti fornisce credenziali ruotabili. Nei log userei identificativi di correlazione senza inserire trascrizioni, token o dati personali per impostazione predefinita. La conservazione dei dati va definita in base alla necessità operativa.
Il trasferimento è una funzione del servizio
Quando il bot non può completare la richiesta, Watson può proporre il passaggio a un operatore. Il backend prepara un contesto minimo e il livello telefonico gestisce il trasferimento. Va previsto anche il fallimento del trasferimento o l’assenza di operatori: una spiegazione chiara e un canale alternativo, senza promettere una connessione che non è disponibile.