Open in

使用您自己的号码（VoIP、API）

通过 SIP 连接 Twilio、Telnyx、SignalWire、Vonage、Plivo 及任何其他 SIP 中继，导入您已拥有的电话号码，让 ThunderPhone 智能体通过这些号码接听和拨打电话。

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

支持的提供商

提供商	`provider` ID	说明
Twilio	`twilio`	账户 SID + 身份验证令牌；每个 Twilio 账户或子账户对应一个连接（参见 Twilio 子账户）
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，您需要在创建步骤中传入该值，以避免为测试重复计费凭据。

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" }
  }'

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：

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。

Twilio 子账户

Twilio 连接绑定到其持有的 Account SID 和 Auth Token 所属的单个 Twilio 账户。Twilio 将电话号码和 SIP 中继保存在各个子账户中，因此使用父账户创建的连接只能看到父账户自己的号码，且现有连接之后无法切换到其他子账户。

若要访问子账户中的号码，请为每个子账户创建一个连接。控制台会为您完成此操作：当您连接的父账户包含活跃子账户时，设置对话框会列出这些子账户，您勾选所需的子账户后，ThunderPhone 会在每个子账户中创建一个连接（以及一个 SIP 中继）。同样的流程也可通过 API 使用：

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

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

# 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 组织的号码：

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"]}'

每次导入都会在您的组织中创建一个电话号码资源，其 number_type="voip" 且 status="provisioning"。

4. 验证每个已导入号码

导入会将号码注册为可用；要实际通过该号码路由通话，还需要完成验证。对于提供商连接（Twilio、Telnyx），这会重新检查提供商凭据和 SIP 可达性。对于手动 SIP连接，系统会先尝试环回自呼叫：ThunderPhone 会从该号码发起一次简短的探测通话，通过您的 SIP 中继，回拨至同一号码。如果这无法验证入站路径，系统会改为发起一次简短的探测通话：从该号码出发，通过您的 SIP 中继，呼叫至一个 ThunderPhone 号码。这些测试会检查中继的用户名、密码、传输方式、出站路由和入站投递。您的运营商会像对待其他通话一样对此类通话计费。

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 号码一样分配呼入／呼出智能体。请参阅处理呼入通话和发起呼出通话。

轮换凭据

当提供商密钥轮换时，重新执行先测试后更新的流程：

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

连接会保持不变——无需重新导入号码。

后续步骤

VoIP 连接参考

连接、验证凭证和导入响应中的所有字段。

电话号码参考

分配智能体、在组织之间转移号码、释放号码。

发起呼出通话

现在您已拥有该号码，可以开始发起呼出通话。