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

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

控制台在 連線 → VoIP（/dashboard/voip-connections）下提供此完整流程的引導式版本： Telnyx 引導式設定會帶你完成帳戶建立與 API 金鑰設定，另有連接既有帳戶的流程，以及具備 AI 設定指南產生器的手動 SIP 表單。

支援的供應商

供應商	`provider` ID	備註
Twilio	`twilio`	API 金鑰 + 密鑰
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..."
  }'

回應為 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"。若失敗，回應會明確說明失敗原因——請修正問題（通常是供應商控制台中缺少中繼指派），然後再次呼叫。

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

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

後續步驟

VoIP 連線參考資料

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

電話號碼參考資料

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

撥打撥出電話

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

Getting Started

Using the dashboard

Connect tools & data

Analyze & improve

Team & account

Compliance

Developer cookbook

Operations

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

支援的供應商

1. 測試憑證

2. 建立連線

3. 列出並匯入號碼

4. 驗證每個匯入的號碼

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

輪替憑證

後續步驟

VoIP 連線參考資料

電話號碼參考資料

撥打撥出電話

​支援的供應商

​1. 測試憑證

​2. 建立連線

​3. 列出並匯入號碼

​4. 驗證每個匯入的號碼

​5. 指派智慧體並接聽通話

​輪替憑證

​後續步驟

VoIP 連線參考資料

電話號碼參考資料

撥打撥出電話

支援的供應商

1. 測試憑證

2. 建立連線

3. 列出並匯入號碼

4. 驗證每個匯入的號碼

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

輪替憑證

後續步驟