使用自有號碼（VoIP、API）
連接 Twilio、Telnyx 或任何 SIP 中繼線路，匯入你已擁有的電話號碼，讓 ThunderPhone 智慧體透過這些號碼接聽與撥打電話。
示範號碼適合用於原型開發，但正式環境流量應透過你自己的 VoIP 供應商使用你擁有的號碼。本指南將帶你完成三步驟流程：測試憑證 → 建立連線 → 匯入號碼 → 驗證。
支援的供應商
| 供應商 | provider 識別碼 | 說明 |
|---|---|---|
| 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" }
}'{
"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"
}'連線會維持不變——無須重新匯入號碼。