接入您自己的号码（VoIP、API）
连接 Twilio、Telnyx 或任何 SIP 中继线路，导入您已有的电话号码，让 ThunderPhone 智能体通过这些号码接听和拨打电话。
演示号码适合原型开发，但生产流量应通过您自己的 VoIP 提供商使用您自有的号码。本指南将带您完成三步流程：测试凭据 → 创建连接 → 导入号码 → 验证。
支持的提供商
| 提供商 | 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" }
}'{
"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"
}'连接会保持不变——无需重新导入号码。