> ## 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.
# Effettua chiamate in uscita (API)
> Avvia una chiamata in uscita gestita dall'IA dal tuo codice: 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, lasciando che l'IA effettui la chiamata per tuo
conto. Casi d'uso tipici:
* Conferme di appuntamenti
* Richiamate per sondaggi
* Follow-up al "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 finestre di chiamata basate sul fuso orario, concorrenza e policy
di tentativi. Questa guida tratta le singole chiamate programmatiche.
## Prerequisiti
Le chiamate in uscita richiedono che tu possieda il `from_number` tramite una
[connessione VoIP](/api-reference/voip-connections). I numeri demo
sono solo per le chiamate in entrata. 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 ne spiega lo scopo — "Salve, Acme chiama per
confermare il suo appuntamento di domani alle 15…" Imposta
`outbound_speak_order` su `agent_first` (l'impostazione predefinita).
Le chiamate in uscita restituiscono `402 Payment Required` se il saldo è ≤
`$0.00`. Ricarica tramite
[`POST /v1/billing/top-up`](/api-reference/billing#top-up-balance)
oppure abilita la [ricarica automatica](/api-reference/billing#update-auto-reload).
## Effettua una chiamata con un agente salvato
Il percorso più semplice — fai riferimento a un agente tramite id:
```bash theme={null}
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": "+14155550199",
"agent_id": 12
}'
```
Risposta:
```json theme={null}
{ "call_id": 987654321, "status": "initiated" }
```
`status: "initiated"` indica 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 theme={null}
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": "+14155550199",
"config": {
"prompt": "You are confirming Jane Doe appointment for 3pm tomorrow…",
"voice": "john",
"product": "spark"
}
}'
```
## Monitora la chiamata
In parallelo, iscriviti al
[webhook `telephony.complete`](/it/webhooks/events) —
il modo più rapido per sapere che una chiamata è terminata. Se non puoi accettare
webhook in entrata, interroga `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.
## Modalità di errore da gestire
| Errore | Correzione |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `402 Payment Required` | Ricarica il saldo oppure abilita la ricarica automatica |
| `403` chiamate in uscita bloccate (numero demo) | Porta invece un numero VoIP |
| `403` chiamate in uscita bloccate (VoIP non verificato) | Esegui [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number) |
| `404 from_number is not registered to this organization` | Verifica che `from_number` corrisponda a un numero di telefono di tua proprietà |
| `502 Bad Gateway` | Errore SIP / LiveKit transitorio; puoi riprovare in sicurezza |
## Controllare il tempo di attesa
Le chiamate in uscita che durano a lungo perché il destinatario risponde lentamente
(alberi IVR, code) possono essere limitate con `max_hold_seconds`:
```json theme={null}
{
"from_number": "+15551234567",
"to_number": "+14155550199",
"agent_id": 12,
"max_hold_seconds": 120
}
```
L'agente riaggancia se non riceve audio umano negli ultimi
N secondi. Il valore predefinito è 900 (15 minuti).
***
## Passaggi successivi
Tutti i campi della richiesta e i codici di errore.
Invia le chiamate in uscita completate al tuo sistema in streaming.
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.