Open in

使用自己的號碼（VoIP、API）

透過 SIP 連接 Twilio、Telnyx、SignalWire、Vonage、Plivo 與任何其他 SIP 中繼，匯入你已擁有的電話號碼，讓 ThunderPhone 語音智慧體透過這些號碼接聽與撥打電話。

已核准的 ThunderPhone 號碼可撥打外撥電話及執行行銷活動。若你偏好透過自己的 VoIP 供應商使用自有號碼，本指南會帶你完成連線流程：測試憑證 → 建立連線 → 匯入號碼 → 驗證。

支援的供應商

供應商	`provider` ID	備註
Twilio	`twilio`	帳戶 SID + 驗證權杖；每個 Twilio 帳戶或子帳戶各一個連線（請參閱 Twilio 子帳戶）
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，你可在建立步驟中傳入該值，避免測試憑證時重複扣費。

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

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：

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 物件。憑證及其他機密連線值會儲存在伺服器端，後續 GET 請求絕不會以純文字傳回——如要輪替，請重新執行 test，並使用新的驗證證據進行 PATCH。

Twilio 子帳戶

Twilio 連線會繫結至其持有 Account SID 和 Auth Token 的單一 Twilio 帳戶。Twilio 會將電話號碼和 SIP 中繼保留在各個子帳戶內，因此使用父帳戶建立的連線只能看見父帳戶自己的號碼，而且既有連線之後無法切換至其他子帳戶。

如要存取子帳戶所持有的號碼，請為每個子帳戶建立一條連線。控制台會為你處理此作業：當你連接擁有啟用中子帳戶的父帳戶時，設定對話方塊會列出這些子帳戶，你可勾選所需的項目，ThunderPhone 就會在每個子帳戶中建立連線（以及 SIP 中繼）。同樣的流程也可透過 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": "..."}}'

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 }
  ]
}

# 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 組織中的號碼：

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

接著匯入你需要的號碼：

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"]}'

每次匯入都會在你的組織中建立一個電話號碼資源，其 number_type="voip" 和 status="provisioning"。

4. 驗證每個匯入的號碼

匯入會將號碼登記為可用；若要實際透過該號碼路由通話，則需要驗證。對於供應商連線（Twilio、 Telnyx），系統會重新檢查供應商憑證與 SIP 可連線性。對於 手動 SIP 連線，系統會先嘗試迴路自我通話： ThunderPhone 會從該號碼發起一通簡短的測試通話，透過你的 SIP 中繼，回撥至同一個號碼。若無法藉此驗證撥入路徑，系統會改以一通簡短的測試通話，從該號碼發起，透過你的 SIP 中繼，撥至 ThunderPhone 號碼。這些測試會檢查中繼的使用者名稱、密碼、傳輸方式、撥出路由與撥入遞送。你的電信業者會將這些通話依一般通話方式計費。

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 號碼的方式指派呼入／外撥智慧體。請參閱處理呼入通話和撥打外撥電話。

輪替憑證

當供應商金鑰輪替時，請重新執行先測試後更新的流程：

# 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"
  }'

連線會維持不變——無須重新匯入號碼。

後續步驟

VoIP 連線參考資料

連線、驗證證據與匯入回應中的所有欄位。

電話號碼參考資料

指派智慧體、在組織之間轉移號碼、釋放號碼。

撥打外撥電話

現在你已擁有該號碼，可以開始撥打外撥電話。