Open in

使用自有號碼（VoIP、API）

透過 SIP 連接 Twilio、Telnyx、SignalWire、Vonage、Plivo 及任何其他 SIP 中繼，匯入你現有的電話號碼，並讓 ThunderPhone 智能體透過這些號碼接聽及撥出電話。

已獲批准的 ThunderPhone 號碼可撥打外撥電話及執行推廣活動。如果你希望透過自己的 VoIP 供應商使用自有號碼，本指南將帶你完成連接流程：測試憑證 → 建立連接 → 匯入號碼 → 驗證。

支援的供應商

供應商	`provider` ID	備註
Twilio	`twilio`	帳戶 SID + Auth Token；每個 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，你可在建立步驟中傳入此 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 絕不會傳回這些權杖。每個新連線其後會以與手動建立連線完全相同的方式匯入及驗證號碼。如要同時為每個新連線的 SIP 中繼啟用通話轉接，請加入 "enable_transfers": true；如該操作失敗，錯誤會記錄於該連線的 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 連線，如該些 Allowed Source IPs 會封鎖實際入站通話，入站通話測試亦會失敗。

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 連線參考資料

連線、驗證證據及匯入回應中的每個欄位。

電話號碼參考資料

指派智能體、在機構之間轉移、釋放號碼。

撥出通話

現在你已擁有該號碼，可以開始撥出。