Tangani panggilan masuk (API)

Menyeluruh: konfigurasikan agen, tetapkan ke nomor telepon, terima panggilan, dan periksa transkrip.

Alur kanonis untuk "menjawab telepon dengan AI", dari terminal Anda. Anda akan:

1. Membuat agen dengan Prompt dan suara.
2. Menyediakan (atau membawa) nomor telepon dan menetapkan agen sebagai penangan panggilan masuknya.
3. Menelepon nomor tersebut. Amati log panggilan, transkrip, dan rekaman.

Total panggilan API: empat. Total waktu: kurang dari lima menit.

1. Buat agen#

Sebuah agen menggabungkan prompt, suara, dan tingkatan produk yang akan menangani panggilan. Anda juga dapat menetapkan batas panggilan seperti max_call_duration_seconds dan ring_duration_seconds pada agen. Agen juga mendukung intro_clip dan intro_ring_count untuk memutar intro yang direkam sebelumnya dan hingga dua dering sebelum agen berbicara. Agen baru juga memerlukan zona waktu. Jika agen Anda multibahasa, Anda dapat menetapkan language_switching untuk mengontrol apakah agen bertanya sebelum berganti bahasa atau mengikuti bahasa penelepon. Lihat Agen untuk setiap kolom konfigurasi; konfigurasi minimumnya adalah:

curl -X POST https://api.thunderphone.com/v1/agents \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":    "Acme Support",
    "prompt":  "You are a friendly support agent for Acme. Help callers with orders and returns. Keep answers short.",
    "voice":   "john",
    "product": "spark"
  }'

Simpan id yang dikembalikan — Anda akan memerlukannya pada langkah 2.

2. Dapatkan nomor telepon#

Jika Anda hanya memerlukan sesuatu untuk dihubungi, dapatkan nomor ThunderPhone dari kumpulan nomor ThunderPhone:

curl -X POST https://api.thunderphone.com/v1/phone-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"area_code": "415"}'

Respons mencakup id dan number dalam format E.164. Nomor ThunderPhone dimulai dengan status="provisioning" dan menjadi active dalam beberapa detik — lakukan polling GET /v1/phone-numbers/{id} untuk memantau transisinya jika diperlukan.

3. Tetapkan agen#

Hubungkan agen dari langkah 1 dengan arah panggilan masuk nomor tersebut:

curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/{phone_id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inbound_agent_id": 12}'

Selesai — nomor tersebut aktif. Setelah panggilan keluar disetujui untuk organisasi Anda, Anda juga dapat menetapkan outbound_agent_id dalam PATCH yang sama. Hingga saat itu, API menolak penetapan tersebut dengan 400.

Jika Anda merutekan panggilan masuk melalui webhook konfigurasi alih-alih inbound_agent_id tetap, webhook tersebut kini dapat mengembalikan timezone per panggilan bersama dengan agent_id dan variables.

4. Terima panggilan#

Hubungi nomor tersebut dari ponsel Anda. Agen menjawab, memperkenalkan diri sesuai Prompt Anda, lalu percakapan dimulai.

Saat panggilan berlangsung, panggilan tersebut muncul di GET /v1/calls dengan status="in_progress". Saat berakhir, rekaman diperbarui dengan end_reason, duration_seconds, billable_minutes, dan (pada akhirnya) URL rekaman serta penilaian AI.

Panggilan masuk diperhitungkan dalam batas panggilan bersamaan organisasi Anda (secara default 20 panggilan sedang berlangsung, dibagikan dengan panggilan keluar, web, dan pengujian). Panggilan yang tiba saat batas telah tercapai akan ditolak sebelum agen menjawab dan diputus, tidak ditagihkan, serta dicatat sebagai panggilan gagal dengan alasan akhir concurrent_call_limit_reached. Kirim email ke support@thunderphone.com jika Anda memerlukan batas yang lebih tinggi.

5. Periksa hasilnya#

Ambil daftar panggilan terbaru:

curl 'https://api.thunderphone.com/v1/calls?limit=5' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Ambil transkripnya:

curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Dan URL rekamannya (berlaku singkat, ditandatangani):

curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Jika Anda berlangganan ke webhook telephony.complete, Anda akan menerima data yang sama sebagai POST ke server Anda — lihat call.complete.

Jika agen Anda memiliki kolom ekstraksi yang dikonfigurasi, payload panggilan yang selesai juga dapat menyertakan data hasil ekstraksi terstruktur.

Langkah berikutnya#