> ## 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.
# Porta i tuoi numeri (VoIP, API)
> Collega Twilio o Telnyx — o qualsiasi trunk SIP — e importa i numeri di telefono dal tuo account esistente.
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.
```bash theme={null}
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 theme={null}
{
"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:
```bash theme={null}
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 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:
```bash theme={null}
curl https://api.thunderphone.com/v1/voip-connections/5/available-numbers \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
Quindi importa quelli desiderati:
```bash theme={null}
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 `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).
```bash theme={null}
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](/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 nuovamente il flusso test e aggiornamento:
```bash theme={null}
# 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
Tutti i campi 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.