接入您自己的号码（VoIP、API）

演示号码适合原型开发，但生产环境流量应通过您自己的 VoIP 提供商使用您拥有的号码。本指南将带您完成三步流程：测试凭据 → 创建连接 → 导入号码 → 验证。

控制台在 连接 → VoIP（/dashboard/voip-connections）下提供了此完整流程的引导版本：包括引导您完成账户创建和 API 密钥配置的 Telnyx 引导设置、连接现有账户的路径，以及带有 AI 设置指南生成器的手动 SIP 表单。

支持的提供商

提供商	`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，您需要在创建步骤中传入该值，以避免对凭据测试重复收费。

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。

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

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

4. 验证每个导入的号码

导入会将号码注册为可用；要实际通过该号码路由通话，需要进行一次往返验证（入站拨入检查 + 出站授权探测）。

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. 分配智能体并接听通话

号码验证完成后，您可以像处理演示号码一样分配入站／出站智能体。请参阅处理入站通话和发起出站通话。

轮换凭据

当服务商密钥轮换时，请重新执行“先测试，再更新”的流程：

# 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 连接参考

连接、验证凭据和导入响应中的每个字段。

电话号码参考

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

发起出站通话

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

Getting Started

Using the dashboard

Connect tools & data

Analyze & improve

Team & account

Developer cookbook

Operations

接入您自己的号码（VoIP、API）

支持的提供商

1. 测试凭据

2. 创建连接

3. 列出并导入号码

4. 验证每个导入的号码

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

轮换凭据

后续步骤

VoIP 连接参考

电话号码参考

发起出站通话

​支持的提供商

​1. 测试凭据

​2. 创建连接

​3. 列出并导入号码

​4. 验证每个导入的号码

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

​轮换凭据

​后续步骤

VoIP 连接参考

电话号码参考

发起出站通话

支持的提供商

1. 测试凭据

2. 创建连接

3. 列出并导入号码

4. 验证每个导入的号码

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

轮换凭据

后续步骤