Getting Started

Concetti fondamentali

Una mappa di tutto ciò che c’è nella piattaforma: cosa fa ogni oggetto, dove si trova nella dashboard e quale API lo utilizza.

ThunderPhone è una piattaforma completa per creare, eseguire e migliorare agenti vocali IA. Questa pagina è la mappa: ogni concetto che incontrerai, una breve sezione per ciascuno, con la relativa area della dashboard e l'API che lo supporta. Scorrila una volta, poi torna qui ogni volta che un termine richiede una spiegazione.

La barra laterale della dashboard rispecchia questa struttura:

Organizzazioni#

Un'organizzazione è l'unità di tenancy. Ogni altra risorsa — agenti, numeri di telefono, chiamate, chiavi — appartiene a una sola organizzazione. Il tuo account può appartenere a più organizzazioni; ciascuna ha il proprio saldo, le proprie chiavi e il proprio elenco di membri.

La chiave API sk_live_ che crei in Organizzazione → Chiavi è vincolata a un'organizzazione. Questo vincolo rende l'API REST così semplice: non inserisci mai un ID organizzazione nei percorsi URL, perché la tua chiave la identifica già.

Nella dashboard: il selettore dell'organizzazione (nel piè di pagina della barra laterale) e le impostazioni Organizzazione — schede Il mio account, Generali, Chiavi, Avvisi, Impostazioni di fatturazione e Cronologia fatturazione. Consulta il riferimento alle impostazioni dell'organizzazione.

Nell'API: /v1/orgs, /v1/developer/api-keys.

Agenti#

Un agente è la configurazione IA che gestisce una chiamata. Include:

• Un prompt che regola ciò che l'agente dice e il suo comportamento — incluse azioni di chiamata come trasferimenti, pressioni dei tasti e chiusure della chiamata, che sono semplici righe del prompt anziché una configurazione separata.
• Un livello del motore (spark, bolt, storm-*): Spark è ottimizzato per il costo, Bolt per la velocità, Storm per l'intelligenza nei prompt complessi.
• Una voce più una lingua principale e lingue aggiuntive facoltative — l'agente cambia automaticamente quando il chiamante cambia lingua. Consulta Lingue supportate.
• Funzionalità collegate: app connesse, connessioni API, basi di Knowledge, server MCP e strumenti funzione inline.
• Impostazioni di comportamento: ordine di parola, modalità di conferma, traccia di sottofondo, timeout di attesa.

Le modifiche nel builder vengono salvate automaticamente in una bozza; nulla va online finché non fai clic su Distribuisci. Ogni distribuzione viene salvata come snapshot nella scheda Cronologia del builder, così puoi esaminare e ripristinare qualsiasi versione precedente.

Nella dashboard: Agenti vocali → il builder dell'agente (/dashboard/agents). Consulta Crea il tuo primo agente vocale.

Nell'API: /v1/agents — CRUD, duplicazione, trasferimento, cronologia delle versioni e strumenti di supporto per i prompt.

Voci#

La libreria vocale contiene le voci che un agente può usare, i relativi campioni riproducibili, le lingue compatibili, i raggruppamenti per genere e accento e gli eventuali supplementi per voci o lingue premium. Un servizio di prova a pagamento può sintetizzare una frase personalizzata di 1–500 caratteri prima della scelta.

Le organizzazioni idonee possono anche creare voci personalizzate da un breve campione WAV o MP3. Le voci personalizzate hanno una quota e uno stato di creazione asincrono; quando sono pronte, vengono visualizzate nello stesso selettore dell'agente delle voci della libreria.

Nella dashboard: Voci (/dashboard/voices). Consulta Libreria vocale e voci personalizzate.

Nell'API: /v1/voices, campioni vocali e voci personalizzate.

Numeri di telefono#

Un numero di telefono appartiene a un'organizzazione e instrada le chiamate in entrata verso un agente (e può gestire le chiamate in uscita). Due fonti:

• Numeri demo — numeri statunitensi reali forniti dal pool di ThunderPhone, attivi in pochi secondi. Solo per le chiamate in entrata, rispondono con una breve dichiarazione vocale e la dashboard limita ogni organizzazione a 10 numeri. Perfetti per un primo test, non per la produzione.
• Numeri VoIP — forniti dal proprio provider tramite una connessione VoIP. Twilio e Telnyx si collegano direttamente (Telnyx offre una configurazione guidata); SignalWire e Vonage saranno disponibili a breve — oggi puoi raggiungerli tramite configurazione SIP manuale, che accetta qualsiasi trunk SIP. Una volta importati e verificati, i numeri VoIP supportano chiamate in entrata e in uscita.

Ogni riga del numero consente di impostare una modalità di instradamento, scegliere l'agente per le chiamate in entrata ed etichettare il numero.

Nella dashboard: Numeri di telefono (/dashboard/phone-numbers). Consulta Ottieni un numero di telefono.

Nell'API: /v1/phone-numbers, /v1/voip-connections, /v1/phone-number-labels.

Chiamate#

Ogni chiamata in entrata, chiamata in uscita, simulazione e sessione widget diventa un registro chiamate. Una chiamata include la trascrizione completa con ruoli contrassegnati, la cronologia strutturata dei turni (incluse le chiamate agli strumenti), una registrazione, il totale fatturato e, in modo opzionale, valutazioni AI e segnalazioni di problemi.

Mentre una chiamata è in corso, puoi aprirla e ascoltarla: ti unisci silenziosamente e nessuno nella chiamata ti sente. Dopo aver iniziato ad ascoltare, puoi sussurrare: digita un'istruzione che arriva direttamente al tuo agente durante la chiamata; il chiamante non la sente mai e l'agente la segue in tempo reale.

Nella dashboard: Cronologia chiamate (/dashboard/call-history) per l'archivio e i dettagli di ogni chiamata; In diretta per le chiamate in corso. Consulta Esamina, ascolta e guida le tue chiamate.

Nell'API: /v1/calls — elenco, trascrizione, cronologia, audio, valutazione, esportazione; /v1/issue-reports.

Portali clienti#

Un portale clienti è una vista brandizzata e di sola lettura della cronologia chiamate per un cliente esterno. Gli amministratori dell'organizzazione scelgono gli agenti le cui chiamate vengono visualizzate, aggiungono le email dei visualizzatori approvati, caricano un logo e un colore di accento e, facoltativamente, verificano un dominio personalizzato. I visualizzatori del portale possono esaminare i dettagli delle chiamate, le trascrizioni e le registrazioni disponibili senza ricevere accesso alla dashboard.

Nella dashboard: Portali clienti (/dashboard/client-portals). Consulta Portali clienti.

Nell'API: /v1/client-portals per l'interfaccia di gestione amministrativa.

Widget web#

Il widget web offre ai visitatori del tuo sito una conversazione tramite microfono con un agente, senza bisogno di un numero di telefono. Si autentica con una chiave pubblicabile (pk_live_...) vincolata all'origine dei tuoi domini consentiti, quindi è sicura nel codice lato client.

Le chiavi funzionano in una di due modalità: agent (associata staticamente a un agente) oppure webhook (il tuo server sceglie la configurazione per ogni visitatore; vedi Configurazione dinamica per chiamata). Le sessioni del widget utilizzano la stessa infrastruttura di chiamata delle chiamate telefoniche.

Nella dashboard: Widget web (/dashboard/web-widgets) — crea widget, imposta la modalità e l'agente, gestisci i domini consentiti e copia lo snippet di incorporamento. Vedi Crea un widget web.

Nell'API: /v1/publishable-key, /v1/mic-session e la documentazione SDK del widget.

Basi di conoscenza#

Una base di conoscenza è un insieme di documenti che il tuo agente può cercare durante una chiamata per basare le sue risposte su informazioni attendibili: carica file, incolla testo oppure importa pagine web tramite URL, quindi associa la base di conoscenza a un agente nel builder. L'agente la interroga con uno strumento di ricerca integrato ogni volta che la conversazione lo richiede.

Nella dashboard: Knowledge (/dashboard/knowledge) per la libreria di documenti; la sezione Knowledge del builder per associarne una a un agente. Vedi Fornisci una base di conoscenza al tuo agente.

Connessioni#

Le connessioni permettono agli agenti di raggiungere il mondo esterno. Quattro tipi, un unico gruppo nella barra laterale:

• App (/dashboard/app-connections) — connessioni OAuth a Slack, HubSpot, Salesforce, Google Calendar, Google Sheets e Cal.com. Connettiti una volta, quindi abilita per operazione gli strumenti (inviare un messaggio Slack, aggiornare o creare un contatto HubSpot, prenotare uno slot Cal.com…) per qualsiasi agente. Vedi Connetti app.
• API (/dashboard/api-connections) — trasforma qualsiasi API HTTP in un' azione dell'agente. Incolla un comando cURL e la procedura guidata AI prepara la definizione dello strumento, oppure creala manualmente; un pulsante Testa richiesta esegue una chiamata sandbox prima della pubblicazione. Vedi Connessioni API — l'interfaccia dashboard di /v1/integrations.
• MCP (/dashboard/mcp-connections) — aggiungi un server Model Context Protocol tramite URL e consenti all'agente di utilizzare gli strumenti che espone. Vedi Aggiungi un server MCP.
• VoIP (/dashboard/voip-connections) — credenziali del provider per utilizzare i tuoi numeri di telefono. Vedi Connetti un provider VoIP.

ThunderPhone espone anche il proprio endpoint MCP affinché un client MCP esterno possa elencare gli agenti, ispezionare chiamate e trascrizioni ed effettuare chiamate. Vedi Usa ThunderPhone come server MCP.

Nell'API: /v1/integrations, /v1/mcp-servers e /v1/voip-connections; vedi anche Crea un'integrazione di strumenti.

Campagne#

Una campagna effettua chiamate in uscita su larga scala: carica un CSV di contatti, scegli l'agente e il numero chiamante e imposta la finestra di chiamata (giorni e orari, con fuso orario), la concorrenza e la politica di ripetizione (numero massimo di tentativi e risultati da riprovare: nessuna risposta, segreteria telefonica, errore). La campagna procede nell'elenco e registra ogni chiamata nella Cronologia chiamate.

Nella dashboard: Campagne (/dashboard/campaigns). Vedi Esegui una campagna di chiamate in uscita.

Per chiamate programmatiche una tantum: l' API delle chiamate in uscita.

Monitoraggio in tempo reale#

Live mostra ogni chiamata in corso nell'organizzazione e consente di aprirne una qualsiasi per ascoltare e sussurrare in tempo reale. È l'interfaccia di supervisione: osserva un nuovo prompt ricevere il suo primo traffico reale oppure monitora una campagna in corso.

Nella dashboard: Live (/dashboard/live). Vedi Osservare e supervisionare le chiamate in tempo reale.

Simulazioni#

Una simulazione è un chiamante IA che intrattiene una conversazione reale con il tuo agente — stesso percorso telefonico, trascrizione reale, valutazione reale — così puoi eseguire test prima (e dopo) della pubblicazione. Indirizzala a un agente o a un numero di telefono, scrivi tu lo scenario del chiamante oppure genera scenari con l'IA dal prompt dell'agente (inclusi i casi limite, se lo chiedi) e osserva la chiamata in tempo reale.

Gli scenari vengono raggruppati in suite che fissano una percentuale minima di superamento e possono bloccare le release in CI; le regressioni rispetto alla baseline accettata vengono riportate per ogni scenario.

Nella dashboard: Simulations (/dashboard/simulations), oltre al pulsante Simulazione nel builder dell'agente. Vedi Simulare una chiamata.

Nell'API: /v1/test-calls e il runner delle suite — vedi Testare un agente end-to-end.

Set di convalida#

Un set di convalida trasforma momenti reali delle chiamate in controlli di regressione ripetibili a singolo turno. Ogni esempio conserva il contesto della conversazione, l'audio pertinente del chiamante, la risposta originale e il comportamento previsto. Le riproduzioni vengono eseguite sulla bozza corrente dell'agente senza effettuare un'altra chiamata e la finestra di distribuzione può mostrare se l'ultima esecuzione corrisponde ancora a quella bozza.

Nella dashboard: Validation sets (/dashboard/validation) per il dataset dell'organizzazione e la scheda Convalida del builder dell'agente per le esecuzioni. Vedi Set di convalida.

Nell'API: /v1/validation-sets e gli endpoint di riproduzione agente/esempio nella stessa pagina di riferimento.

Esperimenti#

Un esperimento esegue test A/B delle configurazioni dell'agente sul traffico in tempo reale: definisci varianti (prompt, motori o impostazioni diversi), distribuisci il traffico tra di esse e confronta i risultati per variante. Usalo invece di implementare manualmente la logica dei bucket in un webhook.

Nella dashboard: Experiments (/dashboard/experiments) e la scheda A/B nel builder dell'agente. Vedi Esperimenti (test A/B).

Problemi#

Un problema è un inconveniente segnalato su una chiamata specifica — registrato da un revisore umano o rilevato dalla valutazione IA. I problemi includono gravità, origine e stato, e la pagina Problemi è la coda di triage: filtra, ispeziona la chiamata problematica e monitora le correzioni.

Nella dashboard: Issues (/dashboard/issues), oltre alla segnalazione per chiamata nella Cronologia chiamate. Vedi Triage dei problemi.

Nell'API: /v1/issue-reports.

Report#

Un report risponde a una domanda in linguaggio naturale sui dati delle tue chiamate ("Quali sono stati i tre principali motivi per cui i chiamanti hanno chiesto di parlare con una persona la scorsa settimana?") con un'analisi scritta dall'IA, limitata agli agenti e all'intervallo di date che scegli.

Nella dashboard: Reports (/dashboard/reports). Vedi Report.

Osservabilità#

Observability è l'interfaccia delle metriche: volume delle chiamate, risultati e qualità nel tempo, filtrabili per agente e intervallo temporale, con esportazione per analisi successive.

Nella dashboard: Observability (/dashboard/observability). Vedi Observability.

Avvisi#

Una regola di avviso monitora una metrica (percentuale di successo, percentuale di errore, punteggio medio, volume delle chiamate, regressioni delle suite) in una finestra temporale e si attiva quando supera la soglia definita. Le notifiche vengono inviate via email e Slack e attivano un evento alert.triggered nei tuoi endpoint webhook.

Nella dashboard: Organization → Alerts. Vedi Avvisi.

Webhook#

ThunderPhone invia webhook HTTP POST al tuo server quando si verificano eventi durante e dopo una chiamata. Due modelli di consegna:

• Endpoint webhook (consigliati): gestisci molti URL in /v1/developer/webhook-endpoints con segreti per endpoint e sottoscrizioni agli eventi per endpoint.
• Webhook legacy con URL singolo: un URL per organizzazione. Gestito in /v1/webhook o in Organizzazione → Generale. Mantenuto per la compatibilità con le versioni precedenti.

Gli eventi si dividono in due classi:

• Gli eventi bloccanti si aspettano che il tuo server risponda con una configurazione che determina la chiamata in corso — gli eventi di chiamata in arrivo (telephony.incoming / web.incoming). Hai fino a 10 secondi per rispondere; in caso di timeout, l'agente assegnato staticamente gestisce la chiamata.
• Gli eventi non bloccanti sono notifiche fire-and-forget, ritentate con backoff esponenziale — vedi semantica di consegna.

Ogni richiesta include una firma HMAC-SHA256 in X-ThunderPhone-Signature. Vedi Verifica della firma.

Strumenti funzione#

Uno strumento funzione è un endpoint HTTP che il tuo agente può chiamare nel corso di una conversazione. Fornisci a ThunderPhone uno schema di funzione in stile OpenAI insieme a un URL dell'endpoint; l'agente decide quando chiamarlo e ThunderPhone effettua la richiesta HTTP firmata dai suoi server e restituisce il risultato all'agente.

Gli agenti includono anche funzionalità di chiamata integrate — trasferire la chiamata, inviare input da tastierino (DTMF), terminare la chiamata, attendere in attesa — che abiliti con semplici righe di prompt anziché con definizioni di strumenti.

Nella dashboard: la sezione Connessioni API del builder (vedi Connessioni).

Nell'API: /v1/integrations e la specifica Function Tools.

Team e ruoli#

Ogni organizzazione dispone di un elenco di membri con due ruoli: i Membri creano e gestiscono gli agenti; gli Amministratori gestiscono anche il team e la fatturazione. Invita tramite email — gli inviti scadono dopo 7 giorni e possono essere revocati; il menu ⋯ nella riga di un membro modifica i ruoli o rimuove una persona. Il single sign-on può essere configurato per l'intera organizzazione — vedi SSO.

Nella dashboard: Organizzazione → Generale. Vedi Invita il tuo team.

Nell'API: /v1/members, /v1/invites.

Fatturazione#

ThunderPhone è prepagato. Ogni organizzazione dispone di un saldo in USD; le chiamate lo addebitano alla tariffa al minuto dell'agente (livello del motore più supplementi — il builder mostra in tempo reale la tariffa complessiva mentre modifichi le impostazioni, e lingue aggiuntive selezionate aggiungono 3¢/min). Quando il saldo raggiunge zero, le chiamate in entrata vengono rifiutate e le chiamate in uscita restituiscono 402 Payment Required.

Ricarica manualmente oppure abilita la ricarica automatica con una soglia di saldo, un importo di ricarica e un limite di spesa mensile facoltativo — così una chiamata non si interrompe mai a metà frase.

Nella dashboard: Organizzazione → Impostazioni di fatturazione e Cronologia fatturazione. Vedi Aggiungi fondi e attiva la ricarica automatica, oltre al riferimento completo dei prezzi.

Nell'API: /v1/billing.

Il copilota nell'app#

La dashboard include un copilota integrato — chiedigli "come faccio a X" e risponde in base a questa documentazione, offre guide passo passo che evidenziano i controlli effettivi e può riprodurre qualsiasi tour guidato. È il modo più rapido per trovare un controllo menzionato in questa pagina. Vedi Chiedi al copilota nell'app.

Mettere tutto insieme#