Usa i tuoi numeri (VoIP, API)

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.

Provider supportati#

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.

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" }
  }'

{
  "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:

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 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:

# 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": "..."}}'

{
  "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 }
  ]
}

# 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:

curl https://api.thunderphone.com/v1/voip-connections/5/available-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Quindi importa quelli desiderati:

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 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.

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 e Effettuare chiamate in uscita.

Rotazione delle credenziali#

Quando una chiave del provider viene ruotata, esegui di nuovo il flusso test-e-aggiornamento:

# 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#