> ## 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`）下提供了此完整流程的引导版本：包括引导您完成账户创建和 API 密钥配置的 Telnyx 引导设置、连接现有账户的路径，以及带有 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/guides/handle-inbound-calls) 和
[发起出站通话](/zh/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/guides/place-outbound-calls">
    现在您已拥有该号码，可以开始发起出站通话。
  </Card>
</CardGroup>