Developer cookbook

Lakukan panggilan keluar (API)

Picu panggilan keluar berbasis AI dari kode Anda sendiri — untuk alur survei, tindak lanjut, atau konfirmasi.

Panggilan keluar memungkinkan Anda menyerahkan nomor tujuan dan konfigurasi agen kepada ThunderPhone agar AI melakukan panggilan atas nama Anda. Kasus penggunaan umum:

• Konfirmasi janji temu
• Panggilan balik survei
• Tindak lanjut "percobaan kedua" setelah panggilan terlewat
• Notifikasi bergaya dispatch

Prasyarat#

1. Sediakan nomor VoIP

   Panggilan keluar mengharuskan Anda memiliki from_number melalui koneksi VoIP. Nomor demo hanya untuk panggilan masuk. Lihat Gunakan nomor Anda sendiri.

2. Buat agen

   Prompt bernuansa panggilan keluar biasanya dimulai dengan agen memperkenalkan diri dan tujuannya — "Halo, ini Acme yang menelepon untuk mengonfirmasi janji temu Anda besok pukul 15.00…" Atur outbound_speak_order ke agent_first (default).

3. Pertahankan saldo positif

   Panggilan keluar mengembalikan 402 Payment Required jika saldo ≤ $0.00. Isi saldo melalui POST /v1/billing/top-up atau aktifkan isi ulang otomatis.

Lakukan panggilan dengan agen tersimpan#

Cara paling sederhana — referensikan agen berdasarkan 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
  }'

Respons:

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

Lakukan panggilan dengan konfigurasi inline#

Jika Anda menginginkan Prompt sekali pakai yang tidak perlu disimpan sebagai agen, gunakan config. Bentuknya sesuai dengan skema respons dari 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"
    }
  }'

Pantau panggilan#

Secara paralel, berlangganan ke webhook telephony.complete — cara tercepat untuk mengetahui panggilan telah selesai. Jika Anda tidak dapat menerima webhook masuk, lakukan polling GET /v1/calls/{call_id} setiap beberapa detik; rekaman mencakup end_reason, duration_seconds, dan URL rekaman setelah panggilan berakhir.

Mode kegagalan yang perlu ditangani#

Mengontrol waktu tunggu#

Panggilan keluar yang berlangsung lama karena pihak yang dihubungi lambat merespons (pohon IVR, antrean) dapat dibatasi dengan max_hold_seconds:

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

Agen mengakhiri panggilan jika tidak ada audio manusia yang diterima dalam N detik terakhir. Defaultnya adalah 900 (15 menit).

Langkah berikutnya#