> ## 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.

# Gestisci le chiamate in entrata (API)

> Dall'inizio alla fine: configura un agente, assegnalo a un numero di telefono, ricevi una chiamata e ispeziona la trascrizione.

<Note>
  Stai creando il tuo primo agente a mano? La dashboard ti guida in questo
  esatto flusso — crea l'agente, aggiungi un numero, simula, rivedi — con una
  procedura guidata. Inizia dal
  [quickstart della dashboard](/it/quickstart-dashboard).
</Note>

Il flusso canonico per "rispondere 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 riunisce il prompt, la voce e il livello di prodotto che gestiranno
la chiamata. Consulta [Agenti](/api-reference/agents) per ogni campo di configurazione;
il minimo è:

```bash theme={null}
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.

<Tip>
  Scegli `spark` per domande e risposte semplici al costo più basso, `bolt` quando
  la velocità conta più di tutto. Passa a `storm-base-with-ack` quando il tuo prompt
  richiede un ragionamento più approfondito e può tollerare mezzo secondo di riempitivo
  mentre il modello pensa. Consulta i
  [livelli di prodotto](/api-reference/agents#product-tiers-at-a-glance).
</Tip>

## 2. Ottieni un numero di telefono

Se ti serve solo un numero da chiamare, provisiona un numero demo
dal pool di ThunderPhone:

```bash theme={null}
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 demo
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 monitorare la transizione, se ti interessa.

<Note>
  Per la produzione, evita i numeri demo e
  [porta i tuoi numeri tramite VoIP](/it/guides/bring-your-own-numbers).
  I numeri demo sono solo per le chiamate in entrata e hanno un volume limitato.
</Note>

## 3. Assegna l'agente

Associa l'agente del passaggio 1 alla direzione in entrata del numero:

```bash theme={null}
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. Puoi anche impostare `outbound_agent_id`
nello stesso PATCH, così il numero sarà pronto anche per effettuare chiamate in uscita.

## 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"`. Al termine, il record viene aggiornato con
`end_reason`, `duration_seconds`, `billable_minutes` e, infine,
un URL della registrazione e una valutazione IA.

## 5. Esamina i risultati

Recupera l'elenco delle chiamate recenti:

```bash theme={null}
curl 'https://api.thunderphone.com/v1/calls?limit=5' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

Recupera la trascrizione:

```bash theme={null}
curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

E l'URL della registrazione (firmato e di breve durata):

```bash theme={null}
curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

Se ti sei iscritto al
[webhook `telephony.complete`](/it/webhooks/events)
riceverai gli stessi dati come POST al tuo server — consulta
[call.complete](/it/webhooks/call-complete).

***

## Passaggi successivi

<CardGroup cols={2}>
  <Card title="Configurazione dinamica per chiamata" icon="bolt" href="/it/guides/dynamic-call-config">
    Scegli un agente diverso per ogni chiamante in base al numero di telefono o
    a una logica personalizzata in un webhook.
  </Card>

  <Card title="Aggiungi integrazioni di strumenti" icon="screwdriver-wrench" href="/it/guides/build-tool-integration">
    Consenti all'agente di chiamare le tue API durante la conversazione.
  </Card>

  <Card title="Ricevi webhook call.complete" icon="bolt" href="/it/webhooks/call-complete">
    Invia ogni chiamata completata al tuo CRM / flusso di analisi.
  </Card>

  <Card title="Valutazione AI e report sui problemi" icon="chart-line" href="/api-reference/calls#ai-call-grading">
    Valuta automaticamente ogni chiamata e inoltra quelle segnalate per la revisione.
  </Card>
</CardGroup>