Developer cookbook

Menangani panggilan masuk (API)

Dari awal hingga akhir: konfigurasi agen, tetapkan ke nomor telepon, terima panggilan, dan periksa transkrip.

Alur kanonis "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#

Agen menggabungkan Prompt, suara, dan tingkat produk yang akan menangani panggilan. Lihat Agen untuk setiap kolom konfigurasi; minimum yang diperlukan 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 membutuhkannya pada langkah 2.

2. Dapatkan nomor telepon#

Jika Anda hanya memerlukan nomor untuk dihubungi, sediakan nomor demo dari kumpulan 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 menyertakan id dan number dalam format E.164. Nomor demo dimulai dengan status="provisioning" dan menjadi active dalam beberapa detik — lakukan polling pada GET /v1/phone-numbers/{id} untuk memantau perubahan jika diperlukan.

3. Tetapkan agen#

Kaitkan 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. Anda juga dapat menetapkan outbound_agent_id dalam PATCH yang sama agar nomor tersebut juga siap melakukan panggilan keluar.

4. Terima panggilan#

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

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

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 transkrip:

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

Dan URL rekaman (berumur 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.

Langkah berikutnya#