Effettua chiamate in uscita (API)

Avvia dal tuo codice 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, affinché l'IA effettui la chiamata per tuo conto. Casi d'uso tipici:

• Conferme di appuntamenti
• Richiamate per sondaggi
• Follow-up di "secondo tentativo" dopo una chiamata persa
• Notifiche in stile dispatch

Prerequisiti#

1. Scegli un numero abilitato alle chiamate in uscita

   Usa un numero di tua proprietà tramite una connessione VoIP, oppure richiedi l'autorizzazione per usare i tuoi numeri ThunderPhone per le chiamate in uscita dalla pagina Phone Numbers. I numeri ThunderPhone sono inizialmente abilitati solo alle chiamate in entrata. ThunderPhone esamina manualmente ogni richiesta; una volta approvati, tali numeri possono effettuare chiamate fino al limite giornaliero approvato (che si reimposta alle 00:00 UTC) ed eseguire campagne, e puoi richiedere un limite più elevato. I numeri VoIP del cliente non hanno limiti giornalieri, quindi li consigliamo per le chiamate in uscita. 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 spiega il proprio scopo — "Salve, sono Acme e la chiamo per confermare il suo appuntamento di domani alle 15:00…" Imposta outbound_speak_order su agent_first (il valore predefinito).

3. Mantieni un saldo positivo

   Le chiamate in uscita restituiscono 402 Payment Required se il saldo è ≤ $0.00. Ricarica il saldo o abilita la ricarica automatica in Organizzazione → Impostazioni di fatturazione nella dashboard. La tua chiave sk_live_ può controllare il saldo con GET /v1/billing, ma non può ricaricare il saldo né modificare 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":   "+14155552671",
    "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":   "+14155552671",
    "config": {
      "prompt":  "You are confirming Jane Doe appointment for 3pm tomorrow…",
      "voice":   "john",
      "product": "spark"
    }
  }'

Monitora la chiamata#

In parallelo, abbonati al webhook telephony.complete — il modo più rapido per sapere che una chiamata è terminata. Se non puoi accettare webhook in entrata, effettua il polling di 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.

Se il tuo agente è configurato per estrarre dati strutturati dopo la chiamata, tali dati vengono inviati separatamente al termine della finalizzazione.

Passa variabili per chiamata a un agente salvato#

Gli agenti salvati possono usare segnaposto come {{name}} o {{name|there}} nel testo del prompt. Quando effettui una chiamata in uscita con agent_id, passa variables con i valori per quella chiamata:

{
  "from_number": "+[REDACTED_PHONE]",
  "to_number": "+[REDACTED_PHONE]",
  "agent_id": 12,
  "variables": {
    "name": "Jordan"
  }
}

Usa valori stringa indicizzati per nome del segnaposto. Queste variabili si applicano agli agenti salvati; l'esempio config inline di questa guida non le utilizza.

Modalità di errore da gestire#

Consulta il riferimento alle chiamate in uscita per l'elenco completo e stabile dei codici di idoneità e per entrambe le forme di risposta 409. Se un numero attivo diventa non idoneo dopo l'accettazione della richiesta ma prima dell'avvio della chiamata, il controllo finale restituisce il payload 409 non ripetibile.

Controllare il tempo di attesa#

Le chiamate in uscita che si prolungano perché il destinatario risponde lentamente (alberi IVR, code) possono essere limitate con max_hold_seconds:

{
  "from_number": "+15551234567",
  "to_number":   "+14155552671",
  "agent_id":    12,
  "max_hold_seconds": 120
}

L'agente riaggancia se non ha ricevuto audio umano negli ultimi N secondi. Il valore predefinito è 900 secondi (15 minuti).

Passaggi successivi#