---
title: "Gestisci le chiamate in entrata (API)"
description: "Dall'inizio alla fine: configura un agente, assegnalo a un numero di telefono, ricevi una chiamata e ispeziona la trascrizione."
---
Stai creando il tuo primo agente manualmente? La dashboard segue esattamente
questo flusso — crea l'agente, aggiungi un numero, simula, controlla — con una
procedura guidata. Inizia dalla
[guida rapida della dashboard](/it/quickstart-dashboard).
Il flusso canonico "rispondi al telefono con un'IA", dal tuo terminale.
Dovrai:
1. Creare un agente con un prompt e una voce.
2. Provisionare (o portare) un numero di telefono e assegnare l'agente come gestore
delle chiamate in entrata.
3. Chiamare il numero. Osservare il registro chiamate, la trascrizione e la registrazione.
Chiamate API totali: quattro. Tempo totale: meno di cinque minuti.
## 1. Crea un agente
Un agente raggruppa il prompt, la voce e il livello di prodotto che gestiranno
la chiamata. Puoi anche impostare limiti per le chiamate, come `max_call_duration_seconds`
e `ring_duration_seconds`, sull’agente. Gli agenti supportano anche un `intro_clip`
e `intro_ring_count` per riprodurre un’introduzione preregistrata e fino a due squilli prima
che l’agente parli. I nuovi agenti richiedono anche un fuso orario. Se il tuo agente è
multilingue, puoi impostare `language_switching` per controllare se chiede prima di cambiare
lingua o se segue la lingua del chiamante.
Consulta [Agenti](/api-reference/agents) per tutti i campi di configurazione; il
minimo è:
```bash
curl -X POST https://api.thunderphone.com/v1/agents \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme Support",
"prompt": "You are a friendly support agent for Acme. Help callers with orders and returns. Keep answers short.",
"voice": "john",
"product": "spark"
}'
```
Salva l'`id` restituito — ti servirà nel passaggio 2.
Scegli `spark` per semplici domande e risposte al costo più basso, `bolt` quando
la velocità conta più di tutto. Passa a `storm-base-with-ack` quando il prompt
richiede un ragionamento più approfondito e può tollerare mezzo secondo di riempitivo
mentre il modello elabora. Consulta i
[livelli di prodotto](/api-reference/agents#product-tiers-at-a-glance).
## 2. Ottieni un numero di telefono
Se ti serve solo qualcosa da chiamare, ottieni un numero ThunderPhone
dal pool di ThunderPhone:
```bash
curl -X POST https://api.thunderphone.com/v1/phone-numbers \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"area_code": "415"}'
```
La risposta include un `id` e un `number` in formato E.164. I numeri ThunderPhone
iniziano con `status="provisioning"` e diventano `active` entro pochi
secondi — esegui il polling di
[`GET /v1/phone-numbers/{id}`](/api-reference/phone-numbers#retrieve-a-phone-number)
per osservare la transizione, se ti interessa.
I numeri ThunderPhone iniziano solo per le chiamate in entrata. Un amministratore
dell'organizzazione può richiedere le chiamate in uscita dalla pagina Phone Numbers.
ThunderPhone esamina manualmente ogni richiesta; una volta approvati, i numeri possono
effettuare chiamate ed eseguire campagne. I numeri VoIP del cliente restano invariati.
## 3. Assegna l'agente
Associa l'agente del passaggio 1 alla direzione in entrata del numero:
```bash
curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/{phone_id} \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"inbound_agent_id": 12}'
```
Tutto qui — il numero è attivo. Dopo che le chiamate in uscita sono state approvate per la tua
organizzazione, puoi anche impostare `outbound_agent_id` nella stessa PATCH. Fino ad
allora, l'API rifiuta tale assegnazione con `400`.
Se instradi le chiamate in entrata tramite un webhook di configurazione anziché un valore fisso di `inbound_agent_id`, quel webhook ora può restituire un `timezone` per chiamata insieme a `agent_id` e `variables`.
## 4. Ricevi una chiamata
Chiama il numero dal tuo telefono. L'agente risponde, si presenta
secondo il tuo prompt e la conversazione inizia.
Mentre la chiamata è in corso, appare in
[`GET /v1/calls`](/api-reference/calls#list-calls) con
`status="in_progress"`. Quando termina, il record si aggiorna con
`end_reason`, `duration_seconds`, `billable_minutes` e, infine,
un URL della registrazione e una valutazione dell'IA.
Le chiamate in entrata concorrono al
[limite di chiamate simultanee](/api-reference/introduction#call-limits) della tua organizzazione (per impostazione predefinita, 20
chiamate in corso, condivise con chiamate in uscita, web e di test). Una chiamata che arriva quando il limite è stato raggiunto viene rifiutata prima che l'agente risponda e interrotta, non viene addebitata e viene registrata come chiamata non riuscita con motivo di fine `concurrent_call_limit_reached`. Invia un'email a support@thunderphone.com se hai
bisogno di un limite più alto.
## 5. Esamina i risultati
Recupera l'elenco delle chiamate recenti:
```bash
curl 'https://api.thunderphone.com/v1/calls?limit=5' \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
Recupera la trascrizione:
```bash
curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
E l'URL della registrazione (firmato, a breve scadenza):
```bash
curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
Se hai sottoscritto il
[webhook `telephony.complete`](/it/webhooks/events),
riceverai gli stessi dati come POST sul tuo server — vedi
[call.complete](/it/webhooks/call-complete).
Se il tuo agente ha campi di estrazione configurati, il payload della chiamata
completata può includere anche dati estratti strutturati.
---
## Passaggi successivi
Scegli un agente diverso per ogni chiamante in base al numero di telefono o
a una logica personalizzata in un webhook.
Consenti all'agente di chiamare le tue API durante la conversazione.
Instrada direttamente i chiamanti oppure verifica la destinazione prima di connetterli.
Invia ogni chiamata conclusa in streaming al tuo CRM / pipeline di analisi.
Valuta automaticamente ogni chiamata e instrada quelle segnalate per la revisione.