---
title: "使用您自己的号码（VoIP、API）"
description: "通过 SIP 连接 Twilio、Telnyx、SignalWire、Vonage、Plivo 及任何其他 SIP 中继，导入您已拥有的电话号码，让 ThunderPhone 智能体通过这些号码接听和拨打电话。"
---

已获批准的 ThunderPhone 号码可以拨打外呼电话并运行活动。如果您希望通过自己的 VoIP 提供商使用您拥有的号码，本指南将带您完成连接流程：**测试凭据 → 创建连接 → 导入号码 → 验证**。

<Note>
  控制台在 **连接 → VoIP**（`/dashboard/voip-connections`）下提供了整个流程的引导式版本：首先是连接现有号码的路径（Twilio 和 Telnyx 使用 API 密钥；SignalWire、Vonage、Plivo 及任何其他中继线路则通过手动 SIP 表单，并提供特定于服务商的步骤和 AI 设置指南生成器），其次是引导式设置，可开通新的 Telnyx 账户。
</Note>

## 支持的提供商

| 提供商 | `provider` ID | 说明 |
|----------|---------------|-------|
| Twilio | `twilio` | 账户 SID + 身份验证令牌；每个 Twilio 账户或子账户对应一个连接（参见 [Twilio 子账户](#twilio-subaccounts)） |
| Telnyx | `telnyx` | API 密钥；提供引导式接入（`setup_method: guided_telnyx`） |
| SignalWire | `signalwire` | 无原生提供商连接；使用 SignalWire SIP 预设将其连接为 `manual` |
| Vonage | `vonage` | 无原生提供商连接；使用 Vonage SIP 预设将其连接为 `manual` |
| 手动 SIP | `manual` | 任何 SIP 中继，包括 SignalWire、Vonage 和 Plivo。如果您从控制台中的任一此类提供商卡片开始，连接仍为 `manual`，并会将选择存储在 `sip_config.preset` 中（`signalwire`、`vonage` 或 `plivo`） |

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

响应为一个状态为 `status="connected"` 的 [VoipConnection 对象](/api-reference/voip-connections#connection-object)。

凭据存储在服务器端，后续 GET 请求绝不会以明文形式返回。若要轮换凭据，请重新执行一次 `test`，然后使用新的验证凭据执行 PATCH。

### Twilio 子账户

Twilio 连接绑定到其持有的 Account SID 和 Auth Token 所属的单个 Twilio 账户。Twilio 将电话号码和 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 绝不会返回这些令牌。每个新连接随后都会像您手动创建的连接一样导入并验证号码。
添加 `"enable_transfers": true` 还可为每个新连接的 SIP 中继启用呼叫转接；如果该操作失败，错误会在该
连接的 `test_result.transfer_enable_error` 中报告，但不会导致该行失败。

## 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)，
其 `number_type="voip"` 且 `status="provisioning"`。

## 4. 验证每个已导入号码

导入会将号码注册为*可用*；要实际通过该号码路由通话，还需要完成验证。对于提供商连接（Twilio、Telnyx），这会重新检查提供商凭据和 SIP 可达性。对于**手动 SIP**连接，系统会先尝试环回自呼叫：ThunderPhone 会*从*该号码发起一次简短的探测通话，*通过*您的 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"`。您自己的 Telnyx 账户中的号码即使测试通话失败或尚未配置出站，仍可继续接听来电：其状态会变为 `status="active"`，并将 `voip_verification_status` 设为 `unverified`，响应会说明原因。失败时，响应会明确指出失败原因——对于手动中继线路，这会是运营商的 SIP 响应，例如 *“拒绝了 ThunderPhone 的凭据（SIP 401）”* 或 *“无法路由通话（SIP 404）”*——请修复问题（凭据、允许的源 IP，或服务商控制台中缺失的中继线路分配），然后再次调用。

对于已加入允许列表的手动 SIP 连接，如果这些允许的源 IP 会阻止真实的入站通话，入站通话测试也会失败。

## 5. 分配智能体并接听通话

号码验证完成后，您可以像使用 ThunderPhone 号码一样分配呼入／呼出智能体。请参阅[处理呼入通话](/zh/guides/handle-inbound-calls)和[发起呼出通话](/zh/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="/zh/guides/place-outbound-calls">
    现在您已拥有该号码，可以开始发起呼出通话。
  </Card>
</CardGroup>