Concetti fondamentali

Una mappa di tutto ciò che è presente 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 del dashboard e l'API che lo supporta. Scorrila una volta, poi torna qui ogni volta che un termine richiede una spiegazione.

La barra laterale del 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 molte 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 è associata a un'organizzazione. Questa associazione rende l'API REST così lineare: non devi mai inserire un ID organizzazione nei percorsi URL, perché la tua chiave la identifica già.

Nel dashboard: il selettore dell'organizzazione (nel piè di pagina della barra laterale) e le impostazioni Organizzazione — schede per Il mio account, Generale, Chiavi, Avvisi, Impostazioni di fatturazione e Cronologia di fatturazione. Consulta il riferimento delle 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 del tastierino e chiusure della chiamata, che sono semplici righe del prompt anziché configurazioni separate.
• Un livello del motore (spark, bolt, storm-*): Spark è ottimizzato per i costi, Bolt per la velocità, Storm per l'intelligenza su prompt complessi.
• Una voce più una lingua principale e facoltative lingue aggiuntive — l'agente cambia automaticamente quando un 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 ispezionare e ripristinare qualsiasi versione precedente.

Nel 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ò utilizzare, i relativi campioni riproducibili, le lingue compatibili, i raggruppamenti per genere e accento e gli eventuali sovrapprezzi per voci o lingue premium. Un campionatore 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 a un agente (e può gestire le chiamate in uscita). Due fonti:

• Numeri ThunderPhone — numeri statunitensi reali forniti dal pool di ThunderPhone, attivi in pochi secondi, $1/mese più un supplemento di 1¢/min. Inizialmente supportano solo le chiamate in entrata. Un amministratore dell'organizzazione può richiedere le chiamate in uscita dalla pagina Phone Numbers; ThunderPhone esamina ogni richiesta manualmente e i numeri approvati possono effettuare chiamate ed eseguire campagne. Per impostazione predefinita, un'organizzazione può avere 25 numeri.
• Numeri VoIP — forniti dal tuo provider tramite una connessione VoIP. Twilio e Telnyx si connettono direttamente con una chiave API (Telnyx offre anche una procedura guidata per i nuovi account); SignalWire, Vonage, Plivo e qualsiasi altro trunk SIP si connettono tramite la configurazione SIP, una configurazione SIP manuale. Una volta importati e verificati, i numeri VoIP supportano chiamate in entrata e in uscita.

Ogni riga del numero ti 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 identificati, la cronologia strutturata dei turni (incluse le chiamate agli strumenti), una registrazione, il totale di fatturazione e valutazioni AI e report dei problemi facoltativi.

Mentre una chiamata è in corso, puoi aprirla e ascoltarla — ti unisci in silenzio e nessuno nella chiamata ti sente. Una volta in ascolto, 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 corso per le chiamate attive. Consulta Rivedi, 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 visualizzazione con marchio e di sola lettura della cronologia chiamate per un cliente esterno. Gli amministratori dell'organizzazione scelgono gli agenti di cui visualizzare le chiamate, aggiungono email di visualizzatori approvati, caricano un logo e un colore 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 l'accesso alla dashboard.

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

Nell'API: /v1/client-portals per la superficie di gestione amministrativa.

Widget web#

Il widget web offre ai visitatori del tuo sito una conversazione tramite microfono con un agente vocale — senza bisogno di un numero di telefono. Si autentica con una chiave pubblicabile (pk_live_...) che i browser possono usare solo dai domini consentiti, quindi è sicura nel codice lato client. L'elenco dei domini non costituisce autenticazione e le impostazioni della sessione che una pagina può inviare sono disattivate finché non le consenti sulla chiave.

Le chiavi funzionano in una di due modalità: agent (associata staticamente a un agente) oppure webhook (il tuo server seleziona la configurazione per 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 dell'SDK Widget.

Basi di conoscenza#

Una base di conoscenza è un insieme di documenti che il tuo agente può cercare durante una chiamata per fondare le proprie risposte: carica file, incolla testo oppure importa pagine web tramite URL, quindi collega 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 collegarne una a un agente. Vedi Fornisci al tuo agente una base di conoscenza.

Connessioni#

Le connessioni consentono agli agenti di raggiungere il mondo esterno. Quattro tipi, un 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 attiva per operazione gli strumenti (inviare un messaggio Slack, aggiornare o inserire un contatto HubSpot, prenotare uno slot Cal.com…) su 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 Richiesta di test 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, seleziona l'agente e il numero chiamante, quindi imposta la finestra di chiamata (giorni e orari, con fuso orario), la concorrenza e la politica di nuovi tentativi (numero massimo di tentativi e quali esiti — nessuna risposta, segreteria telefonica, errore — vengono ritentati). 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#

In tempo reale mostra ogni chiamata in corso nell'organizzazione e ti consente di aprirne una qualsiasi per ascoltare e sussurrare in tempo reale. È l'interfaccia di supervisione: osserva un nuovo prompt mentre riceve il suo primo traffico reale, oppure tieni d'occhio una campagna in corso.

Nella dashboard: In tempo reale (/dashboard/live). Consulta Guardare 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 testare prima (e dopo) il rilascio. Indirizzala a un agente o a un numero di telefono, scrivi tu stesso 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 i rilasci in CI; le regressioni rispetto alla baseline accettata vengono segnalate per scenario.

Nella dashboard: Simulazioni (/dashboard/simulations), oltre al pulsante Simulazione all'interno del builder dell'agente. Consulta Simulare una chiamata.

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

Set di convalida#

Un set di convalida trasforma momenti di chiamate reali in controlli di regressione ripetibili a turno singolo. Ogni esempio conserva il contesto della conversazione, l'audio rilevante 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: Set di convalida (/dashboard/validation) per il dataset dell'organizzazione e la scheda Convalida del builder dell'agente per le esecuzioni. Consulta 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 reale: definisci varianti (prompt, motori o impostazioni diversi), suddividi 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: Esperimenti (/dashboard/experiments) e la scheda A/B nel builder dell'agente. Consulta Esperimenti (test A/B).

Problemi#

Un problema è un inconveniente segnalato in 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 interessata e monitora le correzioni.

Nella dashboard: Problemi (/dashboard/issues), oltre alla segnalazione per chiamata nella Cronologia chiamate. Consulta 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 un operatore la scorsa settimana?") con un'analisi scritta dall'IA, limitata agli agenti e all'intervallo di date che scegli.

Nella dashboard: Report (/dashboard/reports). Consulta Report.

Osservabilità#

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

Nella dashboard: Osservabilità (/dashboard/observability). Consulta Osservabilità.

Avvisi#

Una regola di avviso monitora una metrica (tasso di successo, tasso di errore, punteggio medio, volume delle chiamate, regressioni della 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 verso i tuoi endpoint webhook.

Nella dashboard: Organizzazione → Avvisi. Consulta 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 singolo URL: un URL per organizzazione. Gestito in /v1/webhook o in Organizzazione → Generale. Mantenuto per 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). Una chiamata telefonica attende fino a 13 secondi, incluso un tentativo, e una sessione widget 10 secondi. Non esiste un agente di fallback: senza una configurazione utilizzabile, la chiamata telefonica viene terminata e la sessione widget non riesce.
• Gli eventi non bloccanti sono notifiche fire-and-forget, riprovate con backoff esponenziale — vedi semantica di consegna.

Ogni richiesta include una firma HMAC-SHA256 con timestamp in X-ThunderPhone-Signature-V2, oltre alla firma legacy basata solo sul corpo X-ThunderPhone-Signature. Vedi Verifica della firma.

Strumenti funzione#

Uno strumento funzione è un endpoint HTTP che il tuo agente può chiamare durante una conversazione. Fornisci a ThunderPhone uno schema di funzione in stile OpenAI e 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à integrate per le chiamate — trasferire la chiamata, inviare input da tastierino (DTMF), terminare la chiamata, attendere in attesa — che abiliti con semplici righe nel prompt anziché con definizioni di strumenti.

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

Nell'API: /v1/integrations e la specifica degli strumenti funzione.

Team e ruoli#

Ogni organizzazione ha un elenco di membri con due ruoli: i Membri creano e gestiscono gli agenti; gli Amministratori gestiscono anche il team e la fatturazione. Invita via 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 scalano in base 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 le 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 ai prezzi.

Nell'API: /v1/billing.

Il copilota nell'app#

La dashboard include un copilota integrato — chiedigli "come faccio a X" e risponderà in base a questa documentazione, offrirà guide passo passo che evidenziano i controlli effettivi e potrà 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#