Gestisci le chiamate in entrata (API)

Dall

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 per tutti i campi 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 qualcosa da chiamare, ottieni un numero ThunderPhone 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 ThunderPhone iniziano con status="provisioning" e diventano active entro pochi secondi — esegui il polling di GET /v1/phone-numbers/{id} per osservare 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. 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 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 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:

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, a breve scadenza):

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

Se il tuo agente ha campi di estrazione configurati, il payload della chiamata completata può includere anche dati estratti strutturati.

Passaggi successivi#