SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场telnyx-voice-curl

telnyx-voice-curl

通用与其它

查看项目

更新于 10-16 02:43

技能介绍

用途

telnyx-voice-curl 提供使用 curl 调用 Telnyx 语音 API 的完整技能说明，面向需要通过 HTTP 请求实现程序化通话控制的开发者。它覆盖外呼、呼入接听、转接、桥接、挂断、拒接、SIP Refer、发送 SIP info 等操作，以及通过 Webhook 接收实时通话事件。

主要能力

  • 发起外呼：POST /calls，必填参数包括 to、from（均为 E.164 格式）和 connection_id（Call Control App 的 UUID）。响应返回 call_control_id、call_leg_id、call_session_id、is_alive、recording_id、call_duration 等字段。
  • 接听呼入：POST /calls/{call_control_id}/actions/answer。
  • 转接实时通话：POST /calls/{call_control_id}/actions/transfer，必填 to。
  • 挂断：POST /calls/{call_control_id}/actions/hangup。
  • 桥接通话：POST /calls/{call_control_id}/actions/bridge，需提供要桥接的另一通话的 call_control_id。
  • 拒接：POST /calls/{call_control_id}/actions/reject，cause 可选 CALL_REJECTED 或 USER_BUSY。
  • 查询通话状态：GET /calls/{call_control_id}。
  • 列出指定 connection 的活跃通话：GET /connections/{connection_id}/active_calls。
  • 列出 Call Control 应用：GET /call_control_applications。
  • 其他操作：创建、获取、更新、删除 Call Control 应用（/call_control_applications），SIP Refer（/calls/{call_control_id}/actions/refer），发送 SIP info（/calls/{call_control_id}/actions/send_sip_info）。
  • Webhook 事件：包括 call.answered、call.hangup、call.initiated、call.bridged 等，用于驱动实时通话状态。

使用方式

curl 在 macOS、Linux 和 Windows 10+ 上预装。通过环境变量设置密钥：

export TELNYX_API_KEY="YOUR_API_KEY_HERE"

所有请求在 Authorization 头中使用 Bearer $TELNYX_API_KEY 认证，Content-Type 为 application/json。例如发起外呼：

curl
-X POST
-H "Authorization: Bearer $TELNYX_API_KEY"
-H "Content-Type: application/json"
-d '{ "to": "+13125550001", "from": "+18005550101", "connection_id": "550e8400-e29b-41d4-a716-446655440000" }'
"https://api.telnyx.com/v2/calls"

错误处理与限制

API 调用可能因网络错误、限流（429）、校验错误（422）或认证错误（401）失败，生产代码应处理错误。常见错误码：401 无效 API 密钥，403 权限不足，404 资源未找到，422 校验错误，429 触发限流（使用指数退避重试）。电话号码必须为 E.164 格式，带 + 前缀和国家代码，不含空格、短横线或括号。列表端点返回分页结果，使用 page[number] 和 page[size] 参数翻页，并检查响应中的 meta.total_pages。

Call Control 是事件驱动的：在 dial() 或收到入站 Webhook 后，须从 Webhook 处理器使用事件载荷中的 call_control_id 发出后续命令。外呼和呼入流程不同：外呼以 dial() 开始，呼入必须先从 incoming Webhook 接听才能执行其他命令。真实的通话控制需要公网可达的 Webhook 端点，否则通话可能接通但应用无法驱动实时通话状态。

Webhook 使用 Ed25519 签名（非对称，非 HMAC/Standard Webhooks）。每个请求包含 telnyx-signature-ed25519（base64 编码的 Ed25519 签名）和 telnyx-timestamp（Unix 时间戳，超过 5 分钟应拒绝以防重放）头部。公钥可从 Telnyx Portal > Account Settings > Keys & Credentials 获取，建议使用对应语言的 Telnyx SDK 进行校验（client.webhooks.unwrap）。端点必须在 2 秒内返回 2xx，否则 Telnyx 将重试（最多 3 次）；可在 Telnyx Portal 配置故障转移 URL。

适用场景

适用于需要以命令行或简单 HTTP 请求集成电话语音能力的开发场景，如呼叫中心、通知拨打、交互式语音应答等。关于收费、价格、具体平台支持等细节，资料未提供。