--- title: "Usa i tuoi numeri (VoIP, API)" description: "Collega Twilio, Telnyx, SignalWire, Vonage, Plivo o qualsiasi altro trunk SIP tramite SIP, importa i numeri di telefono che possiedi già e lascia che gli agenti ThunderPhone rispondano ed effettuino chiamate con essi." --- I numeri ThunderPhone approvati possono effettuare chiamate in uscita ed eseguire campagne. Se preferisci utilizzare numeri di tua proprietà tramite il tuo provider VoIP, questa guida illustra il flusso di connessione: **testa le credenziali → crea la connessione → importa i numeri → verifica**. La dashboard offre una versione guidata dell'intero flusso in **Connessioni → VoIP** (`/dashboard/voip-connections`): prima un percorso per connettere un servizio esistente (Twilio e Telnyx tramite chiave API; SignalWire, Vonage, Plivo e qualsiasi altro trunk tramite il modulo SIP manuale con passaggi specifici per il provider e un generatore di guide alla configurazione basato sull'IA), quindi una configurazione guidata che apre un nuovo account Telnyx. ## Provider supportati | Provider | ID `provider` | Note | |----------|---------------|------| | Twilio | `twilio` | SID account + token di autenticazione; una connessione per account o sottoaccount Twilio (vedi [sottoaccount Twilio](#twilio-subaccounts)) | | Telnyx | `telnyx` | Chiave API; onboarding guidato disponibile (`setup_method: guided_telnyx`) | | SignalWire | `signalwire` | Nessuna connessione provider nativa; collegalo come `manual` con il preset SIP SignalWire | | Vonage | `vonage` | Nessuna connessione provider nativa; collegalo come `manual` con il preset SIP Vonage | | SIP manuale | `manual` | Qualsiasi trunk SIP, inclusi SignalWire, Vonage e Plivo. Se inizi da uno di questi riquadri provider nella dashboard, la connessione resta `manual` e memorizza la scelta in `sip_config.preset` (`signalwire`, `vonage` o `plivo`) | ## 1. Testa le credenziali Prima di creare una connessione VoIP persistente, verifica le credenziali del provider per confermare che funzionino. Verrà restituito un `verification_evidence_id` da passare al passaggio di creazione affinché alle credenziali non venga addebitato due volte il test. ```bash curl -X POST https://api.thunderphone.com/v1/voip-connections/test \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "provider": "telnyx", "credentials": { "apiKey": "KEY...", "connectionId": "123456" }, "sip_config": { "domain": "acme.sip.telnyx.com" } }' ``` ```json Response { "status": "pass", "verification_evidence_id": "b9a2...", "suggested_connection_name": "Telnyx: Acme Main (+15550001234)", "checks": { "credentials_valid": true, "inbound_reachable": true, "outbound_authorized": true } } ``` Se un controllo non riesce, `status` nella risposta sarà `fail` e `checks` mostrerà quale passaggio non è riuscito. Correggi la configurazione lato provider (assegnazione del trunk, elenco IP consentiti, autorizzazione in uscita) e riprova. ## 2. Crea la connessione Passa il `verification_evidence_id` che hai appena ottenuto: ```bash curl -X POST https://api.thunderphone.com/v1/voip-connections \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Acme Telnyx Main", "provider": "telnyx", "setup_method": "api_key", "credentials": { "apiKey": "KEY...", "connectionId": "123456" }, "sip_config": { "domain": "acme.sip.telnyx.com" }, "verification_evidence_id": "b9a2..." }' ``` La risposta è un [oggetto VoipConnection](/api-reference/voip-connections#connection-object) con `status="connected"`. Le credenziali e altri valori segreti della connessione vengono archiviati sul server e non vengono mai restituiti in testo semplice dalle successive richieste GET: per ruotarli, esegui un nuovo `test` e una PATCH con la nuova evidenza. ### Sottoaccount Twilio Una connessione Twilio è associata all'unico account Twilio di cui contiene Account SID e Auth Token. Twilio conserva i numeri di telefono e i trunk SIP all'interno di ogni sottoaccount, quindi una connessione creata con l'account principale vede solo i numeri dell'account principale e una connessione esistente non può essere successivamente trasferita a un altro sottoaccount. Per raggiungere i numeri nei sottoaccount, crea una connessione per ogni sottoaccount. La dashboard lo fa per te: quando connetti un account padre con sottoaccount attivi, la finestra di configurazione li elenca, selezioni quelli desiderati e ThunderPhone crea una connessione (e un trunk SIP) in ciascuno. Lo stesso flusso è disponibile tramite API: ```bash # Discover active subaccounts visible to the parent credentials curl -X POST https://api.thunderphone.com/v1/voip-connections/twilio/subaccounts \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"credentials": {"accountSid": "ACparent...", "authToken": "..."}}' ``` ```json Response { "discovery_id": "7c1e...", "parent": { "sid": "ACparent...", "friendly_name": "Acme" }, "subaccounts": [ { "sid": "ACsupport...", "friendly_name": "Acme Support", "already_connected": false, "connection_id": null }, { "sid": "ACsales...", "friendly_name": "Acme Sales", "already_connected": true, "connection_id": 5 } ] } ``` ```bash # Create a connection for each selected subaccount curl -X POST https://api.thunderphone.com/v1/voip-connections/twilio/subaccounts/connect \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"discovery_id": "7c1e...", "subaccount_sids": ["ACsupport..."]}' ``` La risposta contiene una riga per ogni sottoaccount con `status` pari a `created`, `skipped` (già connesso) o `failed`, oltre a un `error` su cui puoi intervenire. Le righe sono indipendenti, quindi un errore in un sottoaccount non blocca mai gli altri e un `discovery_id` rimane valido per 30 minuti, consentendo di riprovare semplicemente una riga non riuscita. I token dei sottoaccount vengono letti da Twilio al momento della rilevazione e archiviati nella nuova connessione; non vengono mai restituiti dall'API. Ogni nuova connessione importa quindi e verifica i numeri esattamente come una connessione creata manualmente. Aggiungi `"enable_transfers": true` per attivare anche i trasferimenti di chiamata per il trunk SIP di ogni nuova connessione; un errore in quel passaggio viene segnalato nel `test_result.transfer_enable_error` di quella connessione e non causa l'errore della riga. ## 3. Elenca e importa numeri Esamina i numeri visibili alle tue credenziali che non sono già in un'organizzazione ThunderPhone: ```bash curl https://api.thunderphone.com/v1/voip-connections/5/available-numbers \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" ``` Quindi importa quelli desiderati: ```bash curl -X POST https://api.thunderphone.com/v1/voip-connections/5/import-numbers \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"numbers": ["+15550001234", "+15550009999"]}' ``` Ogni importazione diventa una [risorsa numero di telefono](/api-reference/phone-numbers) nella tua organizzazione con `number_type="voip"` e `status="provisioning"`. ## 4. Verifica ogni numero importato L'importazione registra il numero come *disponibile*; per instradare effettivamente le chiamate attraverso di esso è necessaria la verifica. Per le connessioni del provider (Twilio, Telnyx), questa verifica nuovamente le credenziali del provider e la raggiungibilità SIP. Per una connessione **SIP manuale**, tenta prima un'autochiamata in loopback: ThunderPhone effettua una breve chiamata di prova *dal* numero, *attraverso* il tuo trunk SIP, *di nuovo allo stesso numero*. Se questo non verifica il percorso in entrata, passa a una breve chiamata di prova *dal* numero, *attraverso* il tuo trunk SIP, *a* un numero ThunderPhone. Questi test verificano nome utente, password, trasporto, instradamento in uscita e consegna in entrata del trunk. Il tuo operatore fattura queste chiamate come qualsiasi altra. ```bash curl -X POST https://api.thunderphone.com/v1/phone-numbers/{id}/verify-voip \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" ``` In caso di successo, `voip_verification_status` passa a `verified` e il numero entra in `status="active"`. Un numero nel tuo account Telnyx continua a ricevere chiamate in entrata quando la chiamata di test non riesce o l'inoltro in uscita non è ancora configurato: diventa `status="active"` con `voip_verification_status` impostato su `unverified`, e la risposta spiega il motivo. In caso di errore, la risposta specifica cosa non ha funzionato — per un trunk manuale, si tratta della risposta SIP del gestore, ad esempio *"ha rifiutato le credenziali di ThunderPhone (SIP 401)"* oppure *"non è stato possibile instradare una chiamata (SIP 404)"* — correggilo (credenziali, IP sorgente consentiti, un'assegnazione del trunk mancante nella dashboard del provider) e chiama di nuovo. Per una connessione SIP manuale con autorizzazione, il test delle chiamate in entrata fallisce anche se quegli IP sorgente consentiti bloccherebbero una reale chiamata in entrata. ## 5. Assegna gli agenti e ricevi una chiamata Dopo aver verificato il numero, assegni gli agenti in entrata / in uscita come per un numero ThunderPhone. Consulta [Gestire le chiamate in entrata](/it/guides/handle-inbound-calls) e [Effettuare chiamate in uscita](/it/guides/place-outbound-calls). ## Rotazione delle credenziali Quando una chiave del provider viene ruotata, esegui di nuovo il flusso test-e-aggiornamento: ```bash # 1. Test the new credentials curl -X POST https://api.thunderphone.com/v1/voip-connections/test ... # 2. PATCH the connection with the new evidence curl -X PATCH https://api.thunderphone.com/v1/voip-connections/{id} \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "credentials": { "apiKey": "NEW_KEY..." }, "verification_evidence_id": "fresh-evidence-id" }' ``` La connessione resta attiva — non è necessario importare di nuovo i numeri. --- ## Passaggi successivi Ogni campo nelle risposte relative a connessione, evidenza e importazione. Assegna agenti, trasferisci tra organizzazioni, rilascia numeri. Ora che possiedi il numero, inizia a effettuare chiamate in uscita.