Developer cookbook

Gunakan nomor Anda sendiri (VoIP, API)

Hubungkan Twilio atau Telnyx — atau trunk SIP apa pun — impor nomor telepon yang sudah Anda miliki, dan biarkan agen ThunderPhone menjawab serta melakukan panggilan menggunakan nomor tersebut.

Nomor demo cocok untuk pembuatan prototipe, tetapi trafik produksi harus menggunakan nomor yang Anda miliki melalui penyedia VoIP Anda sendiri. Panduan ini menjelaskan alur tiga langkah: uji kredensial → buat koneksi → impor nomor → verifikasi.

Penyedia yang didukung#

1. Uji kredensial#

Sebelum membuat koneksi VoIP tersimpan, uji kredensial penyedia untuk mengonfirmasi bahwa kredensial tersebut berfungsi. Langkah ini mengembalikan verification_evidence_id yang Anda teruskan ke langkah pembuatan agar kredensial tidak dikenai biaya dua kali untuk pengujian.

curl -X POST https://api.thunderphone.com/v1/voip-connections/test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider":    "telnyx",
    "credentials": { "apiKey": "KEY...", "connectionId": "123456" },
    "sip_config":  { "domain": "acme.sip.telnyx.com" }
  }'

{
  "status": "pass",
  "verification_evidence_id": "b9a2...",
  "suggested_connection_name": "Telnyx: Acme Main (+15550001234)",
  "checks": {
    "credentials_valid": true,
    "inbound_reachable": true,
    "outbound_authorized": true
  }
}

Jika ada pemeriksaan yang gagal, status respons akan menjadi fail dan checks akan menunjukkan langkah yang gagal. Perbaiki konfigurasi di sisi penyedia (penetapan trunk, daftar izin IP, otorisasi panggilan keluar) lalu coba lagi.

2. Buat koneksi#

Teruskan verification_evidence_id yang baru saja Anda dapatkan:

curl -X POST https://api.thunderphone.com/v1/voip-connections \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":         "Acme Telnyx Main",
    "provider":     "telnyx",
    "setup_method": "api_key",
    "credentials":  { "apiKey": "KEY...", "connectionId": "123456" },
    "sip_config":   { "domain": "acme.sip.telnyx.com" },
    "verification_evidence_id": "b9a2..."
  }'

Responsnya adalah objek VoipConnection dengan status="connected". Kredensial disimpan di sisi server dan tidak pernah dikembalikan dalam teks biasa oleh GET berikutnya — untuk merotasi, jalankan test baru dan PATCH dengan bukti baru.

3. Cantumkan dan impor nomor#

Periksa nomor yang dapat diakses dengan kredensial Anda dan belum berada dalam organisasi ThunderPhone:

curl https://api.thunderphone.com/v1/voip-connections/5/available-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Lalu impor nomor yang Anda inginkan:

curl -X POST https://api.thunderphone.com/v1/voip-connections/5/import-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"numbers": ["+15550001234", "+15550009999"]}'

Setiap impor menjadi resource nomor telepon dalam organisasi Anda dengan source="voip" dan status="provisioning".

4. Verifikasi setiap nomor yang diimpor#

Pengimporan mendaftarkan nomor sebagai tersedia; untuk benar-benar merutekan panggilan melaluinya diperlukan verifikasi bolak-balik (pemeriksaan panggilan masuk + uji otorisasi panggilan keluar).

curl -X POST https://api.thunderphone.com/v1/phone-numbers/{id}/verify-voip \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Jika berhasil, voip_verification_status berubah menjadi verified dan nomor memasuki status="active". Jika gagal, respons menjelaskan apa yang gagal — perbaiki (sering kali penetapan trunk belum ada di dasbor operator) lalu panggil kembali.

5. Tetapkan agen dan lakukan panggilan#

Setelah nomor diverifikasi, tetapkan agen panggilan masuk / keluar dengan cara yang sama seperti nomor demo. Lihat Tangani panggilan masuk dan Lakukan panggilan keluar.

Merotasi kredensial#

Saat kunci operator dirotasi, jalankan kembali alur uji-lalu-perbarui:

# 1. Test the new credentials
curl -X POST https://api.thunderphone.com/v1/voip-connections/test ...
 
# 2. PATCH the connection with the new evidence
curl -X PATCH https://api.thunderphone.com/v1/voip-connections/{id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": { "apiKey": "NEW_KEY..." },
    "verification_evidence_id": "fresh-evidence-id"
  }'

Koneksi tetap tersedia — tidak perlu mengimpor ulang nomor.

Langkah berikutnya#