> ## Documentation Index > Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt > Use this file to discover all available pages before exploring further. # Concetti fondamentali > Una panoramica di tutto ciò che è presente nella piattaforma — cosa fa ogni oggetto, dove si trova nella dashboard e quale API lo riguarda. ThunderPhone è una piattaforma completa per creare, gestire e migliorare agenti vocali IA. Questa pagina è la mappa: ogni concetto che incontrerai, una breve sezione alla volta, con la relativa area della dashboard e l'API che la supporta. Scorrila una volta, poi torna qui ogni volta che un termine richiede una spiegazione. La barra laterale della dashboard rispecchia questa struttura: [Agenti](#agents), [numeri di telefono](#phone-numbers), [widget web](#web-widgets), [chiamate](#calls), [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 usare. [Simulazioni](#simulations), [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; ognuna 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 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 per Generali, Chiavi, Avvisi, Impostazioni di fatturazione e Cronologia di fatturazione. **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 dei tasti del tastierino e riagganci, che sono normali righe del prompt anziché configurazioni separate. * Un **livello del motore** (`spark`, `bolt`, `storm-*`): Spark è ottimizzato per il costo, Bolt per la velocità, Storm per l'intelligenza con prompt complessi. * Una **voce** più una **lingua principale** e **lingue aggiuntive** facoltative — l'agente passa automaticamente a un'altra lingua quando il chiamante cambia lingua. Consulta [Lingue supportate](/it/guides/supported-languages). * Funzionalità collegate: [app connesse](#connections), [connessioni API](#connections), [basi Knowledge](#knowledge-bases), [server MCP](#connections) e [strumenti funzione](#function-tools) inline. * Impostazioni del comportamento: ordine di parola, modalità di conferma, traccia di sottofondo, timeout di attesa. Le modifiche nel builder **vengono salvate automaticamente in una bozza**; nulla viene pubblicato finché non fai clic su **Distribuisci**. Ogni distribuzione viene salvata nella scheda **Cronologia** del builder, così puoi ispezionare e ripristinare qualsiasi versione precedente. **Nella 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. *** ## Numeri di telefono Un **numero di telefono** appartiene a un'organizzazione e instrada le chiamate in entrata a un agente (e può effettuare chiamate in uscita). Due fonti: * **Numeri demo** — numeri U.S. reali forniti dal pool di ThunderPhone, attivi in pochi secondi. Solo per chiamate in entrata, rispondono con un breve avviso vocale e la dashboard limita un'organizzazione a 10 numeri. Perfetti per un primo test; non per la produzione. * **Numeri VoIP** — forniti dal tuo provider tramite una [connessione VoIP](#connections). Twilio e Telnyx si connettono direttamente (Telnyx offre una configurazione guidata); SignalWire e Vonage arriveranno presto — oggi puoi raggiungerli tramite configurazione SIP manuale, che accetta qualsiasi trunk SIP. Una volta importati e verificati, i numeri VoIP supportano le 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`). Vedi [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 etichettati, la cronologia strutturata dei turni (incluse le chiamate agli strumenti), una registrazione, il totale di fatturazione e, facoltativamente, valutazioni AI e report dei problemi. Quando una chiamata è **in diretta**, puoi aprirla e **ascoltare** — 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 diretta** per le chiamate in corso. Vedi [Rivedi, ascolta e assisti 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). *** ## 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 delle due modalità: `agent` (associata staticamente a un agente) oppure `webhook` (il tuo server sceglie la configurazione per visitatore — vedi [Configurazione dinamica per chiamata](/it/guides/dynamic-call-config)). Le sessioni widget passano attraverso la stessa infrastruttura delle chiamate telefoniche. **Nella dashboard:** **Widget web** (`/dashboard/web-widgets`) — crea widget, imposta modalità e 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 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 basare le proprie risposte — carica file direttamente oppure importali da Google Drive, 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 unico gruppo nella barra laterale: * **App** (`/dashboard/app-connections`) — connessioni OAuth a Slack, HubSpot, Salesforce, Google Calendar, Google Sheets e Cal.com. Connetti una volta, quindi attiva gli strumenti per singola operazione (pubblicare 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 crea una bozza della definizione dello strumento, oppure creala manualmente; un pulsante **Test Request** esegue una chiamata sandbox prima del rilascio. 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 usare gli strumenti che espone. Vedi [Aggiungi un server MCP](/it/guides/mcp-servers). * **VoIP** (`/dashboard/voip-connections`) — credenziali del provider per [usare i tuoi numeri di telefono](#phone-numbers). Vedi [Connetti un provider VoIP](/it/guides/voip-providers). **Nell'API:** [`/v1/integrations`](/api-reference/integrations) 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, scegli l'agente e il numero chiamante e imposta la finestra di chiamata (giorni e orari, in base al 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 singole:** l' [API per le chiamate in uscita](/it/guides/place-outbound-calls). *** ## Monitoraggio live **Live** mostra ogni chiamata in corso nell'organizzazione e consente di aprire qualsiasi chiamata per [ascoltare e sussurrare](#calls) in tempo reale. È la superficie di supervisione: osserva un nuovo prompt mentre riceve il suo primo traffico reale, oppure tieni d'occhio una campagna in esecuzione. **Nella dashboard:** **Live** (`/dashboard/live`). Vedi [Osserva e supervisiona le chiamate live](/it/guides/monitor-live-calls). *** ## Simulazioni Una **simulazione** è un chiamante AI che tiene una conversazione reale con il tuo agente — stesso percorso di telefonia, trascrizione reale, valutazione reale — così puoi testare prima (e dopo) il rilascio. Indirizzala a un agente o a un numero di telefono, scrivi personalmente lo scenario del chiamante oppure **genera scenari con l'AI** dal prompt dell'agente (inclusi i casi limite, se li richiedi), e osserva la chiamata live. Gli scenari sono raggruppati in **suite** che fissano una percentuale minima di superamento e possono bloccare le release in CI; le regressioni rispetto alla baseline accettata vengono segnalate per scenario. **Nella dashboard:** **Simulazioni** (`/dashboard/simulations`), oltre al pulsante **Simulazione** nel generatore di agenti. Vedi [Simula una chiamata](/it/guides/simulate-a-call). **Nell'API:** [`/v1/test-calls`](/api-reference/test-calls) e l' esecutore di suite — vedi [Testa un agente end-to-end](/it/guides/test-agents). *** ## Esperimenti Un **esperimento** esegue test A/B sulle configurazioni degli agenti con traffico live: definisci varianti (prompt, motori o impostazioni diversi), suddividi il traffico tra di esse e confronta gli esiti 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 generatore di agenti. Vedi [Esperimenti (test A/B)](/it/guides/experiments-ab-testing). *** ## Problemi Un **problema** è un inconveniente segnalato su una chiamata specifica, aperto da un revisore umano o rilevato dalla valutazione AI. I problemi includono gravità, origine e stato, e la pagina Problemi è la coda di triage: filtra, esamina la chiamata interessata e monitora le correzioni. **Nella dashboard:** **Problemi** (`/dashboard/issues`), oltre alla segnalazione per chiamata nella Cronologia chiamate. Vedi [Triage dei problemi](/it/guides/issues). **Nell'API:** [`/v1/issue-reports`](/api-reference/issue-reports). *** ## Rapporti Un **rapporto** 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 un operatore umano la scorsa settimana?") con un'analisi scritta dall'AI, limitata agli agenti e all'intervallo di date che scegli. **Nella dashboard:** **Rapporti** (`/dashboard/reports`). Vedi [Rapporti](/it/guides/reports). *** ## Osservabilità L'**osservabilità** è l'area delle metriche: volume delle chiamate, risultati e qualità nel tempo, filtrabili per agente e intervallo temporale, con esportazione per analisi successive. **Nella dashboard:** **Osservabilità** (`/dashboard/observability`). Vedi [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 un intervallo temporale e si attiva quando supera la soglia impostata. Le notifiche vengono inviate via email e Slack e attivano un evento `alert.triggered` nei tuoi [endpoint webhook](/it/webhooks/endpoints). **Nella dashboard:** **Organizzazione → Avvisi**. Vedi [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 a URL singolo**: 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** prevedono che il tuo server risponda con una configurazione che definisce la chiamata in corso — gli [eventi di chiamata in arrivo](/it/webhooks/call-incoming) (`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](/it/webhooks/overview). Ogni richiesta include una firma HMAC-SHA256 in `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 insieme a un URL dell'endpoint; l'agente decide quando chiamarlo e ThunderPhone effettua la richiesta HTTP firmata dai suoi server e passa 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 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 **Admin** 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 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 [le lingue premium](/it/guides/supported-languages) aggiungono 2¢/min). Quando il saldo raggiunge zero, le chiamate in entrata vengono rifiutate e quelle 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 di fatturazione**. Consulta [Aggiungi fondi e attiva la ricarica automatica](/it/guides/billing-and-topups). **Nell'API:** [`/v1/billing`](/api-reference/billing). *** ## Il copilota nell'app La dashboard include un **copilota** integrato: chiedigli "come faccio a X" e risponderà usando 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. Consulta [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: chiamate in entrata, in uscita, configurazione dinamica, strumenti, test. Configura correttamente il controllo HMAC una volta e riutilizzalo ovunque.