Lakukan panggilan keluar (API)

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

Panggilan keluar memungkinkan Anda memberikan nomor tujuan dan konfigurasi agen ke ThunderPhone, lalu AI melakukan panggilan atas nama Anda. Kasus penggunaan umum:

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

Prasyarat#

1. Pilih nomor yang diaktifkan untuk panggilan keluar

   Gunakan nomor yang Anda miliki melalui koneksi VoIP, atau minta izin untuk menggunakan nomor ThunderPhone Anda untuk panggilan keluar dari halaman Phone Numbers. Nomor ThunderPhone awalnya hanya untuk panggilan masuk. ThunderPhone meninjau setiap permintaan secara manual; setelah disetujui, nomor tersebut dapat melakukan panggilan hingga batas harian yang disetujui (diatur ulang pada 00:00 UTC) dan menjalankan kampanye, dan Anda dapat meminta batas yang lebih tinggi. Nomor VoIP pelanggan tidak memiliki batas harian, sehingga kami merekomendasikan nomor tersebut untuk panggilan keluar. Lihat Bawa nomor Anda sendiri.

2. Buat agen

   Prompt bernuansa panggilan keluar umumnya dimulai dengan agen memperkenalkan dirinya 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 ulang atau aktifkan isi ulang otomatis di Organization → Billing Settings pada dasbor. Kunci sk_live_ Anda dapat memeriksa saldo dengan GET /v1/billing, tetapi tidak dapat mengisi ulang atau mengubah isi ulang otomatis.

Lakukan panggilan dengan agen tersimpan#

Cara paling sederhana — rujuk 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":   "+14155552671",
    "agent_id":    12
  }'

Respons:

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

Lakukan panggilan dengan konfigurasi sebaris#

Jika Anda menginginkan Prompt sekali pakai yang tidak layak disimpan sebagai agen, gunakan config. Strukturnya 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":   "+14155552671",
    "config": {
      "prompt":  "You are confirming Jane Doe appointment for 3pm tomorrow…",
      "voice":   "john",
      "product": "spark"
    }
  }'

Ikuti panggilan#

Secara paralel, berlangganan ke webhook telephony.complete — cara tercepat untuk mengetahui bahwa 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.

Jika agen Anda diatur untuk mengekstrak data terstruktur setelah panggilan, data tersebut dikirimkan secara terpisah setelah finalisasi selesai.

Teruskan variabel per panggilan ke agen tersimpan#

Agen tersimpan dapat menggunakan placeholder seperti {{name}} atau {{name|there}} dalam teks Prompt. Saat Anda melakukan panggilan keluar dengan agent_id, teruskan variables dengan nilai untuk panggilan tersebut:

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

Gunakan nilai string yang diberi kunci berdasarkan nama placeholder. Variabel ini berlaku untuk agen tersimpan; contoh config inline dalam panduan ini tidak menggunakannya.

Mode kegagalan yang perlu ditangani#

Lihat referensi panggilan keluar untuk daftar lengkap kode kelayakan stabil dan kedua bentuk respons 409. Jika nomor aktif menjadi tidak memenuhi syarat setelah permintaan diterima tetapi sebelum panggilan dilakukan, pemeriksaan akhir mengembalikan payload 409 yang tidak dapat dicoba ulang.

Mengontrol waktu tunggu#

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

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

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

Langkah berikutnya#