---
title: "使用自己的號碼（VoIP、API）"
description: "透過 SIP 連接 Twilio、Telnyx、SignalWire、Vonage、Plivo 與任何其他 SIP 中繼，匯入你已擁有的電話號碼，讓 ThunderPhone 語音智慧體透過這些號碼接聽與撥打電話。"
---
已核准的 ThunderPhone 號碼可撥打外撥電話及執行行銷活動。若你偏好透過自己的 VoIP 供應商使用自有號碼，本指南會帶你完成連線流程：**測試憑證 → 建立連線 → 匯入號碼 → 驗證**。
控制台在 **連線 → VoIP**（`/dashboard/voip-connections`）下提供此完整流程的引導版本：先是連接既有服務的路徑（Twilio 和 Telnyx 可透過 API 金鑰；SignalWire、Vonage、Plivo 及其他任何中繼則可透過手動 SIP 表單，並提供供應商專屬步驟與人工智慧設定指南產生器），接著是引導式設定，可開立新的 Telnyx 帳戶。
## 支援的供應商
| 供應商 | `provider` ID | 備註 |
|----------|---------------|-------|
| Twilio | `twilio` | 帳戶 SID + 驗證權杖；每個 Twilio 帳戶或子帳戶各一個連線（請參閱 [Twilio 子帳戶](#twilio-subaccounts)） |
| Telnyx | `telnyx` | API 金鑰；提供引導式上線流程（`setup_method: guided_telnyx`） |
| SignalWire | `signalwire` | 無原生供應商連線；請使用 SignalWire SIP 預設集，以 `manual` 方式連線 |
| Vonage | `vonage` | 無原生供應商連線；請使用 Vonage SIP 預設集，以 `manual` 方式連線 |
| 手動 SIP | `manual` | 任何 SIP 中繼，包括 SignalWire、Vonage 和 Plivo。若你從控制台中的其中一個供應商方塊開始，連線仍為 `manual`，並會將選項儲存在 `sip_config.preset`（`signalwire`、`vonage` 或 `plivo`）中 |
## 1. 測試憑證
建立持久化的 VoIP 連線前，先測試供應商憑證以確認其可正常運作。此操作會傳回
`verification_evidence_id`，你可在建立步驟中傳入該值，避免測試憑證時重複扣費。
```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
}
}
```
若任何檢查失敗，回應的 `status` 會是 `fail`，而 `checks` 會顯示失敗的步驟。請修正供應商端設定（中繼線路指派、IP 允許清單、外撥授權）後再試一次。
## 2. 建立連線
傳入你剛取得的 `verification_evidence_id`：
```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..."
}'
```
回應會傳回處於 `status="connected"` 的 [VoipConnection 物件](/api-reference/voip-connections#connection-object)。憑證及其他機密連線值會儲存在伺服器端，後續 GET 請求絕不會以純文字傳回——如要輪替，請重新執行 `test`，並使用新的驗證證據進行 PATCH。
### Twilio 子帳戶
Twilio 連線會繫結至其持有 Account SID 和 Auth Token 的單一 Twilio 帳戶。Twilio 會將電話號碼和 SIP 中繼保留在各個子帳戶內，因此使用父帳戶建立的連線只能看見父帳戶自己的號碼，而且既有連線之後無法切換至其他子帳戶。
如要存取子帳戶所持有的號碼，請為每個子帳戶建立一條連線。控制台會為你處理此作業：當你連接擁有啟用中子帳戶的父帳戶時，設定對話方塊會列出這些子帳戶，你可勾選所需的項目，ThunderPhone 就會在每個子帳戶中建立連線（以及 SIP 中繼）。同樣的流程也可透過 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..."]}'
```
回應會為每個子帳戶提供一列，其中 `status` 為
`created`、`skipped`（已連線）或 `failed`，並附帶你可據以處理的 `error`。各列彼此獨立，因此某個子帳戶失敗不會阻擋其他子帳戶；`discovery_id` 會在 30
分鐘內保持有效，因此只要重新嘗試失敗的列即可。系統會在探索時從 Twilio
讀取子帳戶權杖，並儲存在新的連線中；這些權杖絕不會透過 API 傳回。之後，每個新連線都會如同你手動建立的連線一樣匯入並驗證號碼。
將 `"enable_transfers": true` 加入設定，也可為每個新連線的 SIP 中繼啟用通話轉接；若該操作失敗，會在該連線的
`test_result.transfer_enable_error` 中回報，但不會使該列失敗。
## 3. 列出並匯入號碼
查看你的憑證可見、且尚未位於 ThunderPhone 組織中的號碼：
```bash
curl https://api.thunderphone.com/v1/voip-connections/5/available-numbers \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
接著匯入你需要的號碼：
```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"]}'
```
每次匯入都會在你的組織中建立一個[電話號碼資源](/api-reference/phone-numbers)，
其 `number_type="voip"` 和 `status="provisioning"`。
## 4. 驗證每個匯入的號碼
匯入會將號碼登記為*可用*；若要實際透過該號碼路由通話，則需要驗證。對於供應商連線（Twilio、
Telnyx），系統會重新檢查供應商憑證與 SIP 可連線性。對於 **手動 SIP** 連線，系統會先嘗試迴路自我通話：
ThunderPhone 會*從*該號碼發起一通簡短的測試通話，*透過*你的 SIP
中繼，*回撥至同一個號碼*。若無法藉此驗證撥入路徑，系統會改以一通簡短的測試通話，*從*該號碼發起，*透過*你的 SIP
中繼，*撥至* ThunderPhone 號碼。這些測試會檢查中繼的使用者名稱、
密碼、傳輸方式、撥出路由與撥入遞送。你的電信業者會將這些通話依一般通話方式計費。
```bash
curl -X POST https://api.thunderphone.com/v1/phone-numbers/{id}/verify-voip \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
成功時，`voip_verification_status` 會變更為 `verified`，而該號碼會進入 `status="active"`。你自己的 Telnyx 帳戶中的號碼，若測試通話失敗或尚未設定外撥，仍會持續接聽來電：它會成為 `status="active"`，並將 `voip_verification_status` 設為 `unverified`，回應中會說明原因。失敗時，回應會明確指出
失敗原因——對於手動中繼，這會是電信業者的 SIP 回應，例如 *「拒絕 ThunderPhone 的認證資訊（SIP 401）」* 或 *「無法路由通話（SIP 404）」*——修正問題（認證資訊、允許的來源 IP 位址，或服務供應商控制台中遺漏的中繼指派），然後再次呼叫。
對於已加入允許清單的手動 SIP 連線，若這些允許的來源 IP 位址會阻擋實際的撥入通話，撥入通話測試也會失敗。
## 5. 指派智慧體並接聽通話
驗證號碼後，你可以比照 ThunderPhone 號碼的方式指派呼入／外撥智慧體。請參閱
[處理呼入通話](/zh-Hant/guides/handle-inbound-calls)和
[撥打外撥電話](/zh-Hant/guides/place-outbound-calls)。
## 輪替憑證
當供應商金鑰輪替時，請重新執行先測試後更新的流程：
```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"
}'
```
連線會維持不變——無須重新匯入號碼。
---
## 後續步驟
連線、驗證證據與匯入回應中的所有欄位。
指派智慧體、在組織之間轉移號碼、釋放號碼。
現在你已擁有該號碼，可以開始撥打外撥電話。