Developer cookbook

Gestisci le chiamate in entrata (API)

Dall

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 per ogni campo di configurazione; il minimo è:

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.

2. Ottieni un numero di telefono#

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

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} per monitorare la transizione, se ti interessa.

3. Assegna l'agente#

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

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 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:

curl 'https://api.thunderphone.com/v1/calls?limit=5' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Recupera la trascrizione:

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):

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 riceverai gli stessi dati come POST al tuo server — consulta call.complete.

Passaggi successivi#