---
title: "使用自有號碼（VoIP、API）"
description: "連接 Twilio 或 Telnyx——或任何 SIP 中繼線路——匯入你已擁有的電話號碼，並讓 ThunderPhone 智能體接聽及撥打電話。"
---

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

<Note>
  控制台內設有完整流程嘅引導版本，位於
  **連接 → VoIP**（`/dashboard/voip-connections`）：包括引導你建立 Telnyx 帳戶及設定 API
  金鑰嘅流程、連接現有帳戶嘅方式，以及附設 AI
  設定指南產生器嘅手動 SIP 表單。
</Note>

## 支援嘅供應商

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

## 1. 測試憑證

建立持久化 VoIP 連接前，先測試供應商
憑證以確認可正常運作。此操作會回傳
`verification_evidence_id`，你可在建立步驟中傳入此值，避免為測試而重複收取
憑證費用。

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

### Twilio 子帳戶

Twilio 連線會綁定至其持有 Account SID 與 Auth Token 的單一 Twilio 帳戶。
Twilio 會將電話號碼和 SIP 中繼儲存在各個子帳戶內，因此以父帳戶建立的連線
只會看見父帳戶本身的號碼，而現有連線其後亦無法切換至其他子帳戶（更新會被拒絕，
因為該連線的 SIP 中繼位於原有帳戶內）。

如要存取子帳戶持有的號碼，請為每個子帳戶建立一個連線。控制台可為你完成此操作：
當你連接擁有活躍子帳戶的父帳戶時，設定對話框會列出這些子帳戶，你可勾選所需帳戶，
ThunderPhone 便會在每個帳戶中建立連線（及 SIP 中繼）。API 亦提供相同流程：

```bash
# 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": "..."}}'
```

```json 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 }
  ]
}
```

```bash
# 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 組織中的號碼：

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

然後匯入所需號碼：

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

匯入只會將號碼登記為*可用*；要真正透過該號碼轉駁來電，則需要完成驗證。對於供應商連線（Twilio、Telnyx），系統會重新檢查供應商憑證及 SIP 連通性。對於 **手動 SIP** 連線，系統會*由*該號碼、*經由*你的 SIP 中繼線、*致電至* ThunderPhone 號碼，發出一通短暫的測試通話（數秒後自動掛線）——藉此實際驗證中繼線的使用者名稱、密碼、傳輸方式及撥出路由。你的電訊商會如一般通話般就此通話收費。

```bash
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 號碼相同的方式指派來電／撥出智能體。請參閱
[處理來電](/yue/guides/handle-inbound-calls)及
[撥出電話](/yue/guides/place-outbound-calls)。

## 輪換憑證

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

```bash
# 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="/yue/guides/place-outbound-calls">
    現在你已擁有該號碼，可以開始撥出電話。
  </Card>
</CardGroup>