Developer cookbook

Effettua chiamate in uscita (API)

Avvia una chiamata in uscita gestita dall

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

Prerequisiti#

1. Porta un numero VoIP

   Le chiamate in uscita richiedono che tu possieda il from_number tramite una connessione VoIP. I numeri demo sono solo per le chiamate in entrata. Consulta Porta i tuoi numeri.

2. Crea un agente

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

3. Mantieni un saldo positivo

   Le chiamate in uscita restituiscono 402 Payment Required se il saldo è ≤ $0.00. Ricarica tramite POST /v1/billing/top-up oppure abilita la ricarica automatica.

Effettua una chiamata con un agente salvato#

Il percorso più semplice — fai riferimento a un agente tramite id:

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:

{ "call_id": 987654321, "status": "initiated" }

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:

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

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:

{
  "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#