Developer cookbook

Usa i tuoi numeri (VoIP, API)

Collega Twilio o Telnyx — oppure qualsiasi trunk SIP — importa i numeri di telefono che possiedi già e lascia che gli agenti vocali ThunderPhone rispondano ed effettuino chiamate con essi.

I numeri demo vanno bene per la prototipazione, ma il traffico in produzione deve usare numeri di tua proprietà tramite il tuo provider VoIP. Questa guida illustra il flusso in tre passaggi: 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 confermarne il funzionamento. Viene restituito un verification_evidence_id da passare al passaggio di creazione, così le credenziali non vengono addebitate due volte per i 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, il valore di status nella risposta sarà fail e checks mostrerà quale passaggio è fallito. Correggi la configurazione lato provider (assegnazione del trunk, lista consentita degli 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 sono mai restituite in testo normale dalle richieste GET successive — per ruotarle, esegui un nuovo test e PATCH con la nuova evidenza.

3. Elenca e importa i numeri#

Esamina i numeri visibili con le 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 specifica cosa non ha funzionato — correggilo (spesso un'assegnazione trunk mancante nella dashboard del provider) e ripeti la chiamata.

5. Assegna gli agenti e gestisci una chiamata#

Una volta verificato il numero, assegni gli agenti in entrata / uscita nello stesso modo di un numero demo. Consulta Gestire le chiamate in entrata e Effettuare chiamate in uscita.

Rotazione delle credenziali#

Quando una chiave del provider viene ruotata, ripeti il flusso di 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#