--- title: "Concetti fondamentali" description: "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: [Agenti](#agents), [voci](#voices), [numeri di telefono](#phone-numbers), [widget web](#web-widgets), [chiamate](#calls), [portali clienti](#client-portals), [Knowledge](#knowledge-bases). [Monitoraggio in tempo reale](#live-monitoring) e [campagne](#campaigns) in uscita. [App, API, server MCP e provider VoIP](#connections) che i tuoi agenti possono utilizzare. [Simulazioni](#simulations), [set di convalida](#validation-sets), [esperimenti](#experiments), [problemi](#issues), [report](#reports), [osservabilità](#observability). [Team e ruoli](#team-and-roles), [chiavi API](#organizations), [avvisi](#alerts), [fatturazione](#billing). [Webhook](#webhooks) e [strumenti funzione](#function-tools) per il tuo codice. --- ## 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](/it/guides/organization-settings). **Nell'API:** [`/v1/orgs`](/api-reference/organizations), [`/v1/developer/api-keys`](/api-reference/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](/it/guides/supported-languages). - Funzionalità collegate: [app connesse](#connections), [connessioni API](#connections), [basi di Knowledge](#knowledge-bases), [server MCP](#connections) e [strumenti funzione](#function-tools) 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](/it/guides/build-an-agent). **Nell'API:** [`/v1/agents`](/api-reference/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](/it/guides/voice-library). **Nell'API:** [`/v1/voices`](/api-reference/voices), [campioni vocali](/api-reference/voice-samples) e [voci personalizzate](/api-reference/custom-voices). --- ## 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, {/* rate:phone */}$1/mese più un supplemento di 1¢/min{/* /rate */}. 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](#connections). 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](/it/guides/get-a-phone-number). **Nell'API:** [`/v1/phone-numbers`](/api-reference/phone-numbers), [`/v1/voip-connections`](/api-reference/voip-connections), [`/v1/phone-number-labels`](/api-reference/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](/it/guides/review-calls). **Nell'API:** [`/v1/calls`](/api-reference/calls) — elenco, trascrizione, cronologia, audio, valutazione, esportazione; [`/v1/issue-reports`](/api-reference/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](/it/guides/client-portals). **Nell'API:** [`/v1/client-portals`](/api-reference/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](/it/guides/dynamic-call-config)). 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](/it/guides/embed-a-web-widget-dashboard). **Nell'API:** [`/v1/publishable-key`](/api-reference/publishable-keys), [`/v1/mic-session`](/api-reference/mic-sessions) e la [documentazione dell'SDK Widget](/it/widget/overview). --- ## 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](/it/guides/knowledge-base). --- ## 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](/it/guides/connect-apps). - **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](/it/guides/api-connections) — l'interfaccia dashboard di [`/v1/integrations`](/api-reference/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](/it/guides/mcp-servers). - **VoIP** (`/dashboard/voip-connections`) — credenziali del provider per [utilizzare i tuoi numeri di telefono](#phone-numbers). Vedi [Connetti un provider VoIP](/it/guides/voip-providers). 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](/it/guides/thunderphone-mcp-server). **Nell'API:** [`/v1/integrations`](/api-reference/integrations), [`/v1/mcp-servers`](/api-reference/mcp-servers) e [`/v1/voip-connections`](/api-reference/voip-connections); vedi anche [Crea un'integrazione di strumenti](/it/guides/build-tool-integration). --- ## 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](/it/guides/outbound-campaigns). **Per chiamate programmatiche una tantum:** l' [API delle chiamate in uscita](/it/guides/place-outbound-calls). ## 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](#calls) 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](/it/guides/monitor-live-calls). --- ## 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](/it/guides/simulate-a-call). **Nell'API:** [`/v1/test-calls`](/api-reference/test-calls) e il runner della suite — consulta [Testare un agente end-to-end](/it/guides/test-agents). --- ## 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](/it/guides/validation-sets). **Nell'API:** [`/v1/validation-sets`](/api-reference/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)](/it/guides/experiments-ab-testing). --- ## 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](/it/guides/issues). **Nell'API:** [`/v1/issue-reports`](/api-reference/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](/it/guides/reports). --- ## 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à](/it/guides/observability). --- ## 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](/it/webhooks/endpoints). **Nella dashboard:** **Organizzazione → Avvisi**. Consulta [Avvisi](/it/guides/alerts). --- ## 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`](/it/webhooks/endpoints) con segreti per endpoint e sottoscrizioni agli eventi per endpoint. - **Webhook legacy con singolo URL**: un URL per organizzazione. Gestito in [`/v1/webhook`](/api-reference/organizations#legacy-single-url-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](/it/webhooks/call-incoming) (`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](/it/webhooks/overview). 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](/it/webhooks/overview). --- ## 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](#connections)). **Nell'API:** [`/v1/integrations`](/api-reference/integrations) e la [specifica degli strumenti funzione](/it/tools/overview). --- ## 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](/it/guides/sso). **Nella dashboard:** **Organizzazione → Generale**. Vedi [Invita il tuo team](/it/guides/invite-your-team). **Nell'API:** [`/v1/members`](/api-reference/members), [`/v1/invites`](/api-reference/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](/it/guides/supported-languages) aggiungono {/* rate:language */}3¢/min{/* /rate */}). 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](/it/guides/billing-and-topups), oltre al [riferimento completo ai prezzi](/it/guides/pricing). **Nell'API:** [`/v1/billing`](/api-reference/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](/it/guides/ask-the-copilot). --- ## Mettere tutto insieme La procedura guidata in cinque passaggi: agente → fatturazione → numero → simulazione → revisione. La stessa prima chiamata in quattro chiamate REST. Crea un agente, finanzialo, ottieni un numero, simula e rivedi le chiamate. App OAuth, API personalizzate, server MCP e provider VoIP. Report, osservabilità, esperimenti, problemi e avvisi. Inviti e ruoli, chiavi API, sicurezza e SSO. Le ricette API: in entrata, in uscita, configurazione dinamica, strumenti, test. Esegui correttamente il controllo HMAC una volta e riutilizzalo ovunque.