---
title: "Gunakan nomor Anda sendiri (VoIP, API)"
description: "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**.

<Note>
  Dasbor memiliki versi terpandu dari seluruh alur ini di bawah
  **Koneksi → VoIP** (`/dashboard/voip-connections`): pertama, jalur untuk
  menghubungkan yang sudah ada (Twilio dan Telnyx melalui kunci API; SignalWire,
  Vonage, Plivo, serta trunk lainnya melalui formulir SIP manual dengan
  langkah-langkah khusus operator dan generator panduan penyiapan AI), lalu
  penyiapan terpandu yang membuka akun Telnyx baru.
</Note>

## Penyedia yang didukung

| Provider | ID `provider` | Catatan |
|----------|---------------|---------|
| Twilio | `twilio` | Account SID + Auth Token; satu koneksi per akun atau subakun Twilio (lihat [subakun Twilio](#twilio-subaccounts)) |
| Telnyx | `telnyx` | Kunci API; onboarding terpandu tersedia (`setup_method: guided_telnyx`) |
| SignalWire | `signalwire` | Tidak ada koneksi provider native; hubungkan sebagai `manual` dengan preset SIP SignalWire |
| Vonage | `vonage` | Tidak ada koneksi provider native; hubungkan sebagai `manual` dengan preset SIP Vonage |
| SIP Manual | `manual` | Trunk SIP apa pun, termasuk SignalWire, Vonage, dan Plivo. Jika Anda memulai dari salah satu tile provider tersebut di dashboard, koneksi tetap `manual` dan menyimpan pilihan dalam `sip_config.preset` (`signalwire`, `vonage`, atau `plivo`) |

## 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.

```bash
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" }
  }'
```

```json Response
{
  "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:

```bash
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](/api-reference/voip-connections#connection-object)
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:

```bash
# 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": "..."}}'
```

```json Response
{
  "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 }
  ]
}
```

```bash
# 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:

```bash
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:

```bash
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](/api-reference/phone-numbers)
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.

```bash
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](/id/guides/handle-inbound-calls) dan
[Lakukan panggilan keluar](/id/guides/place-outbound-calls).

## Merotasi kredensial

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

```bash
# 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

<CardGroup cols={2}>
  <Card title="Referensi koneksi VoIP" icon="phone-volume" href="/api-reference/voip-connections">
    Setiap bidang dalam respons koneksi, bukti, dan impor.
  </Card>
  <Card title="Referensi nomor telepon" icon="phone" href="/api-reference/phone-numbers">
    Tetapkan agen, transfer antarorganisasi, lepaskan nomor.
  </Card>
  <Card title="Lakukan panggilan keluar" icon="arrow-up-right" href="/id/guides/place-outbound-calls">
    Setelah Anda memiliki nomor tersebut, mulai lakukan panggilan keluar.
  </Card>
</CardGroup>