---
title: "Effettua chiamate in uscita (API)"
description: "Avvia dal tuo codice una chiamata in uscita gestita dall'IA — flussi di sondaggio, follow-up o conferma."
---
Le chiamate in uscita ti consentono di fornire a ThunderPhone un numero di destinazione e una configurazione dell'agente, affinché l'IA effettui la chiamata per tuo conto. Casi d'uso tipici:
- Conferme di appuntamenti
- Richiamate per sondaggi
- Follow-up di "secondo tentativo" dopo una chiamata persa
- Notifiche in stile dispatch
Devi chiamare un intero elenco? La funzionalità
[**Campagne**](/it/guides/outbound-campaigns) della dashboard
(`/dashboard/campaigns`) accetta un CSV di contatti e gestisce per
te le finestre di chiamata in base al fuso orario, la concorrenza e
la politica di ripetizione. Questa guida tratta le singole chiamate programmatiche.
## Prerequisiti
Usa un numero di tua proprietà tramite una
[connessione VoIP](/api-reference/voip-connections), oppure richiedi l'autorizzazione
per usare i tuoi numeri ThunderPhone per le chiamate in uscita dalla pagina Phone Numbers.
I numeri ThunderPhone sono inizialmente abilitati solo alle chiamate in entrata. ThunderPhone esamina manualmente ogni
richiesta; una volta approvati, tali numeri possono effettuare chiamate fino al
limite giornaliero approvato (che si reimposta alle 00:00 UTC) ed eseguire campagne, e puoi
richiedere un limite più elevato. I numeri VoIP del cliente non hanno limiti giornalieri, quindi li consigliamo
per le chiamate in uscita. Consulta
[Porta i tuoi numeri](/it/guides/bring-your-own-numbers).
Un prompt orientato alle chiamate in uscita tende a iniziare con l'agente che
si identifica e spiega il proprio scopo — "Salve, sono Acme e la chiamo per
confermare il suo appuntamento di domani alle 15:00…" Imposta
`outbound_speak_order` su `agent_first` (il valore predefinito).
Le chiamate in uscita restituiscono `402 Payment Required` se il saldo è ≤
`$0.00`. Ricarica il saldo o abilita la ricarica automatica in
**Organizzazione → Impostazioni di fatturazione** nella dashboard. La tua chiave `sk_live_`
può controllare il saldo con
[`GET /v1/billing`](/api-reference/billing#get-billing-account), ma non
può ricaricare il saldo né modificare la ricarica automatica.
## Effettua una chiamata con un agente salvato
Il percorso più semplice — fai riferimento a un agente tramite id:
```bash
curl -X POST https://api.thunderphone.com/v1/call \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from_number": "+15551234567",
"to_number": "+14155552671",
"agent_id": 12
}'
```
Risposta:
```json
{ "call_id": 987654321, "status": "initiated" }
```
`status: "initiated"` significa solo che la richiesta è stata accettata — la chiamata
**non è ancora connessa**. Interroga
[`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call)
per lo stato in tempo reale (`in_progress` → `completed` / `failed`).
## Effettua una chiamata con configurazione inline
Se vuoi un prompt una tantum che non vale la pena salvare come agente,
passa invece `config`. La struttura corrisponde allo schema di risposta del
[webhook `call.incoming`](/it/webhooks/call-incoming):
```bash
curl -X POST https://api.thunderphone.com/v1/call \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from_number": "+15551234567",
"to_number": "+14155552671",
"config": {
"prompt": "You are confirming Jane Doe appointment for 3pm tomorrow…",
"voice": "john",
"product": "spark"
}
}'
```
## Monitora la chiamata
In parallelo, abbonati al
[webhook `telephony.complete`](/it/webhooks/events) —
il modo più rapido per sapere che una chiamata è terminata. Se non puoi accettare
webhook in entrata, effettua il polling di `GET /v1/calls/{call_id}` ogni paio di secondi; il
record include `end_reason`, `duration_seconds` e l'URL della registrazione
una volta terminata la chiamata.
Se il tuo agente è configurato per estrarre dati strutturati dopo la chiamata,
tali dati vengono inviati separatamente al termine della finalizzazione.
### Passa variabili per chiamata a un agente salvato
Gli agenti salvati possono usare segnaposto come `{{name}}` o `{{name|there}}` nel
testo del prompt. Quando effettui una chiamata in uscita con `agent_id`, passa
`variables` con i valori per quella chiamata:
```json
{
"from_number": "+[REDACTED_PHONE]",
"to_number": "+[REDACTED_PHONE]",
"agent_id": 12,
"variables": {
"name": "Jordan"
}
}
```
Usa valori stringa indicizzati per nome del segnaposto. Queste variabili si applicano agli
agenti salvati; l'esempio `config` inline di questa guida non le utilizza.
## Modalità di errore da gestire
| Errore | Correzione |
|-------|-----|
| `402 Payment Required` | Ricarica il saldo o abilita la ricarica automatica |
| `400` con `code: destination_not_allowed` | ThunderPhone non chiama quel numero: numeri non validi, numeri di emergenza, numeri a tariffa maggiorata, codici brevi o paesi soggetti a sanzioni. Dai numeri ThunderPhone, sono consentiti solo normali numeri statunitensi e canadesi, esclusi quelli a tariffa maggiorata. `reason` indica quale; vedi [destinazioni bloccate](/api-reference/outbound-calls#blocked-destinations) |
| `409` con `retryable: false` per un numero ThunderPhone | Segui il `code`: richiedi le chiamate in uscita nella pagina Numeri di telefono, attendi una revisione in sospeso o usa un altro numero idoneo |
| `429` con `code: platform_outbound_daily_limit_reached` | L'organizzazione ha utilizzato le chiamate in uscita odierne dai numeri ThunderPhone. Attendi `resets_at` (00:00 UTC), richiedi un limite più alto nella pagina Numeri di telefono o chiama da un numero sulla tua connessione VoIP |
| `429` con `code: concurrent_call_limit_reached` | L'organizzazione ha tante chiamate in corso quanto il suo [limite di chiamate simultanee](/api-reference/introduction#call-limits) (20 per impostazione predefinita, incluse chiamate in entrata, in uscita, web e di test). Riprova dopo il numero di secondi indicato nell'header `Retry-After` o al termine di una chiamata; invia un'email a support@thunderphone.com per aumentare il limite |
| `429` con `code: same_number_too_soon` | Hai chiamato lo stesso `to_number` meno di 10 secondi fa. Riprova dopo il numero di secondi indicato nell'header `Retry-After` |
| `409` con `retryable: false` per un numero VoIP del cliente | Correggi lo stato indicato da `code`; per errori di verifica, esegui [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number) |
| Conflitto di idempotenza `409` | Riutilizza la chiave solo con la richiesta normalizzata originale oppure invia una nuova chiave |
| `404 from_number is not registered to this organization` | Verifica che `from_number` corrisponda a un numero di telefono attivo nella tua organizzazione. Questa risposta viene restituita anche da un numero già in fase di attivazione, con errore, in fase di rilascio o rilasciato |
| `500` con solo un campo `detail` | Non è configurato alcun trunk in uscita. Contatta l'assistenza; non si tratta di un problema relativo allo stato del numero che puoi correggere |
| `502 Bad Gateway` | Errore SIP / LiveKit temporaneo; puoi riprovare in sicurezza |
Consulta il [riferimento alle chiamate in uscita](/api-reference/outbound-calls#error-responses)
per l'elenco completo e stabile dei codici di idoneità e per entrambe le forme di risposta `409`.
Se un numero attivo diventa non idoneo dopo l'accettazione della richiesta ma prima
dell'avvio della chiamata, il controllo finale restituisce il payload `409` non ripetibile.
## Controllare il tempo di attesa
Le chiamate in uscita che si prolungano perché il destinatario risponde lentamente
(alberi IVR, code) possono essere limitate con `max_hold_seconds`:
```json
{
"from_number": "+15551234567",
"to_number": "+14155552671",
"agent_id": 12,
"max_hold_seconds": 120
}
```
L'agente riaggancia se non ha ricevuto audio umano negli ultimi
N secondi. Il valore predefinito è 900 secondi (15 minuti).
---
## Passaggi successivi
Ogni campo della richiesta e codice di errore.
Trasmetti le chiamate in uscita terminate al tuo sistema.
Usa la ricarica automatica affinché le chiamate in uscita non falliscano mai per saldo insufficiente.
Esegui un test a secco del tuo agente in uscita prima della produzione.