Lakukan panggilan keluar (API)

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

Menelepon seluruh daftar? Fitur Campaigns di dashboard (/dashboard/campaigns) menerima CSV kontak dan menangani jendela panggilan yang mempertimbangkan zona waktu, konkurensi, dan kebijakan percobaan ulang untuk Anda. Panduan ini membahas panggilan programatis tunggal.

Prasyarat

Sediakan nomor VoIP

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

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

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" }

status: "initiated" hanya berarti permintaan diterima — panggilan belum terhubung. Polling GET /v1/calls/{call_id} untuk status langsung (in_progress → completed / failed).

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

Error	Perbaikan
`402 Payment Required`	Isi saldo atau aktifkan isi ulang otomatis
`403` panggilan keluar diblokir (nomor demo)	Gunakan nomor VoIP sebagai gantinya
`403` panggilan keluar diblokir (VoIP belum diverifikasi)	Jalankan `POST /v1/phone-numbers/{id}/verify-voip`
`404 from_number is not registered to this organization`	Pastikan `from_number` sesuai dengan nomor telepon yang Anda miliki
`502 Bad Gateway`	Kegagalan SIP / LiveKit sementara; aman untuk mencoba lagi

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

Referensi panggilan keluar

Setiap kolom permintaan dan kode error.

Menerima call.complete

Alirkan panggilan keluar yang selesai ke sistem Anda.

Penagihan

Isi ulang otomatis agar panggilan keluar tidak pernah gagal karena saldo.

Menguji agen panggilan keluar

Lakukan dry run agen panggilan keluar Anda sebelum produksi.

Getting Started

Using the dashboard

Connect tools & data

Analyze & improve

Team & account

Developer cookbook

Operations

Lakukan panggilan keluar (API)

Prasyarat

Lakukan panggilan dengan agen tersimpan

Lakukan panggilan dengan konfigurasi inline

Pantau panggilan

Mode kegagalan yang perlu ditangani

Mengontrol waktu tunggu

Langkah berikutnya

Referensi panggilan keluar

Menerima call.complete

Penagihan

Menguji agen panggilan keluar

​Prasyarat

​Lakukan panggilan dengan agen tersimpan

​Lakukan panggilan dengan konfigurasi inline

​Pantau panggilan

​Mode kegagalan yang perlu ditangani

​Mengontrol waktu tunggu

​Langkah berikutnya

Referensi panggilan keluar

Menerima call.complete

Penagihan

Menguji agen panggilan keluar

Prasyarat

Lakukan panggilan dengan agen tersimpan

Lakukan panggilan dengan konfigurasi inline

Pantau panggilan

Mode kegagalan yang perlu ditangani

Mengontrol waktu tunggu

Langkah berikutnya