Porta i tuoi numeri (VoIP, API)

I numeri demo vanno bene per la prototipazione, ma il traffico di produzione dovrebbe usare numeri di tua proprietà tramite il tuo provider VoIP. Questa guida illustra il flusso in tre passaggi: test delle credenziali → creazione della connessione → importazione dei numeri → verifica.

La dashboard offre una versione guidata dell’intero flusso in Connessioni → VoIP (/dashboard/voip-connections): una configurazione guidata di Telnyx che accompagna nella creazione dell’account e delle chiavi API, un percorso per connettere un account esistente e un modulo SIP manuale con un generatore di guida alla configurazione AI.

Provider supportati

Provider	ID `provider`	Note
Twilio	`twilio`	Chiave API + segreto
Telnyx	`telnyx`	Chiave API; onboarding guidato disponibile (`setup_method: guided_telnyx`)
SignalWire	`signalwire`	In arrivo — connettiti oggi tramite SIP manuale
Vonage	`vonage`	In arrivo — connettiti oggi tramite SIP manuale
SIP manuale	`manual`	Qualsiasi trunk SIP — usa la tua configurazione

1. Testa le credenziali

Prima di creare una connessione VoIP persistente, verifica le credenziali del provider per confermare che funzionino. Questo restituisce un verification_evidence_id da passare al passaggio di creazione, così le credenziali non vengono addebitate due volte per 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" }
  }'

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, la risposta status sarà fail e checks mostrerà quale passaggio non è riuscito. Correggi la configurazione lato provider (assegnazione del trunk, allowlist IP, autorizzazione in uscita) e riprova.

2. Crea la connessione

Passa il verification_evidence_id 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 vengono archiviate lato server e non vengono mai restituite in testo in chiaro dalle GET successive — per ruotarle, esegui un nuovo test e applica PATCH con la nuova evidenza.

3. Elenca e importa i 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 source="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 una verifica di andata e ritorno (controllo di chiamata in entrata + sonda di autorizzazione in uscita).

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". In caso di errore, la risposta indica cosa non ha funzionato — correggilo (spesso si tratta di un’assegnazione del trunk mancante nella dashboard del provider) e richiama l’endpoint.

5. Assegna agenti e gestisci una chiamata

Dopo aver verificato il numero, assegna gli agenti in entrata / uscita come faresti per un numero demo. Consulta Gestire le chiamate in entrata e Effettuare chiamate in uscita.

Rotazione delle credenziali

Quando una chiave del provider viene ruotata, esegui nuovamente 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 rimane attiva — non è necessario reimportare i numeri.

Passaggi successivi

Riferimento delle connessioni VoIP

Tutti i campi nelle risposte relative a connessione, evidenza e importazione.

Riferimento dei numeri di telefono

Assegna agenti, trasferisci tra organizzazioni, rilascia numeri.

Effettuare chiamate in uscita

Ora che possiedi il numero, inizia a effettuare chiamate in uscita.

Getting Started

Using the dashboard

Connect tools & data

Analyze & improve

Team & account

Developer cookbook

Operations

Porta i tuoi numeri (VoIP, API)

Provider supportati

1. Testa le credenziali

2. Crea la connessione

3. Elenca e importa i numeri

4. Verifica ogni numero importato

5. Assegna agenti e gestisci una chiamata

Rotazione delle credenziali

Passaggi successivi

Riferimento delle connessioni VoIP

Riferimento dei numeri di telefono

Effettuare chiamate in uscita

​Provider supportati

​1. Testa le credenziali

​2. Crea la connessione

​3. Elenca e importa i numeri

​4. Verifica ogni numero importato

​5. Assegna agenti e gestisci una chiamata

​Rotazione delle credenziali

​Passaggi successivi

Riferimento delle connessioni VoIP

Riferimento dei numeri di telefono

Effettuare chiamate in uscita

Provider supportati

1. Testa le credenziali

2. Crea la connessione

3. Elenca e importa i numeri

4. Verifica ogni numero importato

5. Assegna agenti e gestisci una chiamata

Rotazione delle credenziali

Passaggi successivi