Open in

使用自有號碼（VoIP、API）

連接 Twilio 或 Telnyx——或任何 SIP 中繼線路——匯入你已擁有的電話號碼，並讓 ThunderPhone 智能體接聽及撥打電話。

ThunderPhone 號碼涵蓋來電，但撥出電話及推廣活動需要使用你透過自有 VoIP 供應商持有嘅號碼。本指南會帶你完成以下三個步驟：測試憑證 → 建立連接 → 匯入號碼 → 驗證。

支援嘅供應商

供應商	`provider` 識別碼	備註
Twilio	`twilio`	帳戶 SID + Auth Token；每個 Twilio 帳戶或子帳戶可建立一個連接（參閱 Twilio 子帳戶）
Telnyx	`telnyx`	API 金鑰；提供引導式設定（`setup_method: guided_telnyx`）
SignalWire	`signalwire`	即將推出 ——目前可透過手動 SIP 連接
Vonage	`vonage`	即將推出 ——目前可透過手動 SIP 連接
手動 SIP	`manual`	任何 SIP 中繼線——使用你自己嘅設定

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

回應為一個 VoipConnection 物件，其 status="connected"。憑證會儲存在伺服器端，後續 GET 請求絕不會以純文字形式傳回——如需輪換憑證，請重新執行 test，然後使用新的驗證資料 PATCH。

Twilio 子帳戶

Twilio 連線會綁定至其持有 Account SID 與 Auth Token 的單一 Twilio 帳戶。 Twilio 會將電話號碼和 SIP 中繼儲存在各個子帳戶內，因此以父帳戶建立的連線只會看見父帳戶本身的號碼，而現有連線其後亦無法切換至其他子帳戶（更新會被拒絕，因為該連線的 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 絕不會傳回這些權杖。每個新連線其後都會像你手動建立的連線一樣，匯入及驗證號碼。

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

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

4. 驗證每個已匯入號碼

匯入只會將號碼登記為可用；要真正透過該號碼轉駁來電，則需要完成驗證。對於供應商連線（Twilio、Telnyx），系統會重新檢查供應商憑證及 SIP 連通性。對於 手動 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" 狀態。失敗時，回應會清楚說明失敗原因——如為手動中繼線，將顯示電訊商的 SIP 回應，例如 "rejected ThunderPhone's credentials (SIP 401)" 或 "could not route a call (SIP 404)"——修正問題（憑證、允許的來源 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 連線參考資料

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

電話號碼參考資料

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

撥出電話

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