使用你自有嘅號碼（VoIP、API）

示範號碼適合用於建立原型，但正式環境流量應透過你自有的 VoIP 供應商使用你擁有的號碼。本指南會帶你完成三步流程：測試憑證 → 建立連線 → 匯入號碼 → 驗證。

支援的供應商

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

{
  "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。

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. 驗證每個匯入的號碼

匯入後，系統會將號碼登記為可用；如要實際透過該號碼路由通話，則需要完成一次雙向驗證（入站撥入檢查 + 出站授權探測）。

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" 狀態。失敗時，回應會清楚說明失敗原因——修正問題後（通常是供應商控制台內缺少 Trunk 指派），再重新呼叫。

5. 指派智能體並接聽通話

完成號碼驗證後，你可以如同使用示範號碼一樣，指派入站／出站語音智能體。請參閱 處理入站通話及 撥打出站通話。

輪換憑證

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

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

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

下一步