> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> 連接 Twilio、Telnyx 或任何 SIP 中繼線路，並從現有帳戶匯入電話號碼。

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

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

## 支援的供應商

| 供應商        | `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`，你可在建立步驟中傳入它，避免因測試而重複計費。

```bash theme={null}
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" }
  }'
```

```json Response theme={null}
{
  "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`：

```bash theme={null}
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 物件](/api-reference/voip-connections#connection-object)。
憑證會儲存在伺服器端，後續 GET 請求絕不會以純文字傳回——如需輪替，請執行新的
`test`，並使用新的驗證資料進行 PATCH。

## 3. 列出並匯入號碼

查看你的憑證可見、且尚未位於 ThunderPhone 組織中的號碼：

```bash theme={null}
curl https://api.thunderphone.com/v1/voip-connections/5/available-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

接著匯入你需要的號碼：

```bash theme={null}
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"]}'
```

每次匯入都會在你的組織中建立一個[電話號碼資源](/api-reference/phone-numbers)，
其 `source="voip"` 且 `status="provisioning"`。

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

匯入會將號碼登記為*可用*；若要實際透過該號碼路由通話，
則需要進行雙向驗證（撥入測試＋撥出授權測試）。

```bash theme={null}
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. 指派智慧體並接聽通話

號碼驗證完成後，你可以如同使用示範號碼般指派撥入／撥出智慧體。請參閱
[處理撥入通話](/zh-Hant/guides/handle-inbound-calls) 與
[撥打撥出電話](/zh-Hant/guides/place-outbound-calls)。

## 輪替憑證

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

```bash theme={null}
# 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"
  }'
```

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

***

## 後續步驟

<CardGroup cols={2}>
  <Card title="VoIP 連線參考資料" icon="phone-volume" href="/api-reference/voip-connections">
    連線、驗證證據與匯入回應中的所有欄位。
  </Card>

  <Card title="電話號碼參考資料" icon="phone" href="/api-reference/phone-numbers">
    指派智慧體、在組織之間轉移，以及釋放號碼。
  </Card>

  <Card title="撥打撥出電話" icon="arrow-up-right" href="/zh-Hant/guides/place-outbound-calls">
    現在你已擁有此號碼，可以開始撥打電話。
  </Card>
</CardGroup>