Gunakan nomor Anda sendiri (VoIP, API)

Hubungkan Twilio atau Telnyx, atau SignalWire, Vonage, Plivo, dan SIP trunk lainnya melalui SIP, impor nomor telepon yang sudah Anda miliki, dan biarkan agen ThunderPhone menjawab serta melakukan panggilan melalui nomor tersebut.

Nomor ThunderPhone yang disetujui dapat melakukan panggilan keluar dan menjalankan kampanye. Jika Anda lebih memilih menggunakan nomor milik Anda melalui penyedia VoIP Anda sendiri, panduan ini menjelaskan alur koneksi: 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. 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 pemeriksaan apa pun 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 dan nilai koneksi rahasia lainnya disimpan di sisi server dan tidak pernah dikembalikan dalam teks biasa oleh GET berikutnya — untuk merotasi, jalankan test baru dan PATCH dengan bukti baru.

Subakun Twilio#

Koneksi Twilio terikat pada satu akun Twilio yang Account SID dan Auth Token-nya disimpan. Twilio menyimpan nomor telepon dan trunk SIP di dalam setiap subakun, sehingga koneksi yang dibuat dengan akun induk hanya dapat melihat nomor milik akun induk tersebut, dan koneksi yang sudah ada tidak dapat dialihkan ke subakun lain di kemudian hari.

Untuk mengakses nomor yang disimpan di subakun, buat satu koneksi per subakun. Dasbor melakukannya untuk Anda: ketika Anda menghubungkan akun induk yang memiliki subakun aktif, dialog penyiapan mencantumkannya, Anda mencentang yang diinginkan, dan ThunderPhone membuat koneksi (serta trunk SIP) di masing-masing subakun. Alur yang sama tersedia melalui API:

# Discover active subaccounts visible to the parent credentials
curl -X POST https://api.thunderphone.com/v1/voip-connections/twilio/subaccounts \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"credentials": {"accountSid": "ACparent...", "authToken": "..."}}'

{
  "discovery_id": "7c1e...",
  "parent": { "sid": "ACparent...", "friendly_name": "Acme" },
  "subaccounts": [
    { "sid": "ACsupport...", "friendly_name": "Acme Support", "already_connected": false, "connection_id": null },
    { "sid": "ACsales...",   "friendly_name": "Acme Sales",   "already_connected": true,  "connection_id": 5 }
  ]
}

# Create a connection for each selected subaccount
curl -X POST https://api.thunderphone.com/v1/voip-connections/twilio/subaccounts/connect \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"discovery_id": "7c1e...", "subaccount_sids": ["ACsupport..."]}'

Respons berisi satu baris per subakun dengan status created, skipped (sudah terhubung), atau failed, serta error yang dapat Anda tindak lanjuti. Baris bersifat independen, sehingga kegagalan pada satu subakun tidak pernah memblokir yang lain, dan discovery_id tetap valid selama 30 menit sehingga baris yang gagal dapat dicoba kembali. Token subakun dibaca dari Twilio saat penemuan dan disimpan pada koneksi baru; token tersebut tidak pernah dikembalikan oleh API. Setiap koneksi baru kemudian mengimpor dan memverifikasi nomor persis seperti koneksi yang Anda buat secara manual. Tambahkan "enable_transfers": true untuk juga mengaktifkan transfer panggilan pada trunk SIP setiap koneksi baru; kegagalan di sana dilaporkan dalam test_result.transfer_enable_error koneksi tersebut dan tidak menyebabkan baris gagal.

3. Daftarkan dan impor nomor#

Periksa nomor yang terlihat oleh kredensial Anda dan belum berada di organisasi ThunderPhone:

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

Kemudian 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 di org Anda dengan number_type="voip" dan status="provisioning".

4. Verifikasi setiap nomor yang diimpor#

Mengimpor mendaftarkan nomor sebagai tersedia; agar panggilan benar-benar dirutekan melaluinya, diperlukan verifikasi. Untuk koneksi provider (Twilio, Telnyx), verifikasi ini memeriksa ulang kredensial provider dan keterjangkauan SIP. Untuk koneksi SIP manual, sistem terlebih dahulu mencoba panggilan mandiri loopback: ThunderPhone melakukan panggilan probe singkat dari nomor tersebut, melalui trunk SIP Anda, kembali ke nomor yang sama. Jika ini tidak memverifikasi jalur masuk, sistem beralih ke panggilan probe singkat dari nomor tersebut, melalui trunk SIP Anda, ke nomor ThunderPhone. Pengujian ini memeriksa nama pengguna, kata sandi, transport, perutean keluar, dan pengiriman masuk trunk. Operator Anda menagih panggilan ini seperti panggilan lainnya.

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". Nomor di akun Telnyx Anda sendiri tetap menerima panggilan masuk saat panggilan uji coba gagal atau panggilan keluar belum disiapkan: nomor tersebut menjadi status="active" dengan voip_verification_status ditetapkan ke unverified, dan respons menjelaskan alasannya. Jika gagal, respons merinci apa yang gagal — untuk trunk manual, ini adalah jawaban SIP dari operator, misalnya "menolak kredensial ThunderPhone (SIP 401)" atau "tidak dapat merutekan panggilan (SIP 404)" — perbaiki masalahnya (kredensial, IP sumber yang diizinkan, penetapan trunk yang belum ada di dasbor penyedia) lalu panggil lagi.

Untuk koneksi SIP manual yang masuk daftar izin, pengujian panggilan masuk juga gagal jika IP Sumber yang Diizinkan tersebut akan memblokir panggilan masuk nyata.

5. Tetapkan agen dan lakukan panggilan#

Setelah nomor diverifikasi, Anda menetapkan agen masuk / keluar dengan cara yang sama seperti nomor ThunderPhone. 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 ada — tidak perlu mengimpor ulang nomor.

Langkah berikutnya#