telnyx-voice-ruby

Telnyx Voice - Ruby 是 Telnyx 提供的语音通话控制 Ruby SDK，让开发者能以编程方式管理电话呼叫的生命周期。

用途

该 SDK 面向需要在 Ruby 应用中集成语音通话能力的开发者，主要用途包括：

发起（dial）和接收（answer）电话
转接（transfer）和桥接（bridge）通话
收集 DTMF 按键、发送 SIP 信息、执行 SIP Refer
通过 Webhook 接收实时通话事件（如已接听、挂断、已发起、已桥接）
管理和查询通话控制应用（Call Control Applications）及活跃通话

主要能力

拨出电话：通过 client.calls.dial() 发起呼出，需提供 to（E.164）、from（E.164）和 connection_id（Call Control App 的 UUID）等必填参数，同时支持 timeout_secs、billing_group_id、client_state 等可选参数。

接听呼入电话：通过 client.calls.actions.answer() 应答来电，需传入 call_control_id。

转接通话：通过 client.calls.actions.transfer() 将在线通话转接到指定号码或 SIP URI。

挂断/桥接/拒接：分别通过 hangup()、bridge()、reject() 处理通话结束、两路通话互通以及拒接（可指定 CALL_REJECTED 或 USER_BUSY 原因）。

查询状态：通过 retrieve_status() 获取单个通话的当前状态，或通过 connections.list_active_calls() 列出某连接下的所有活跃通话。

应用管理：支持创建、检索、更新和删除 Call Control Application。

Webhook 验证：Telnyx 使用 Ed25519 对 Webhook 签名，请求头包含 telnyx-signature-ed25519 和 telnyx-timestamp，需通过 client.webhooks.unwrap() 验证签名并解析事件，生产环境应始终验证。

使用方式

安装：gem install telnyx

初始化：

require "telnyx"
client = Telnyx::Client.new(
  api_key: ENV["TELNYX_API_KEY"],
)

拨打电话示例：

response = client.calls.dial(
  connection_id: "7267xxxxxxxxxxxxxx",
  from: "+18005550101",
  to: "+18005550100;secure=srtp"
)
puts(response)

接听来电示例：

response = client.calls.actions.answer("v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ")
puts(response)

Webhook 处理示例（如 Sinatra）：

post "/webhooks" do
  payload = request.body.read
  headers = {
    "telnyx-signature-ed25519" => request.env["HTTP_TELNYX_SIGNATURE_ED25519"],
    "telnyx-timestamp" => request.env["HTTP_TELNYX_TIMESTAMP"],
  }
  begin
    event = client.webhooks.unwrap(payload, headers)
  rescue => e
    halt 400, "Invalid signature: #{e.message}"
  end
  puts "Received event: #{event.data.event_type}"
  status 200
end

分页可使用 .auto_paging_each 自动迭代：page.auto_paging_each { |item| puts item.id }。

适用场景

呼叫中心或客服系统：自动应答、转接、桥接客户与座席
自动语音应答（IVR）：收集 DTMF 输入并驱动后续流程
通话路由与状态监控：查询活跃通话，依据事件做出控制决策
需要将 Telnyx 语音能力嵌入 Ruby 后端服务的项目

限制与注意事项

必须使用事件驱动模型：呼叫控制在 dial() 或收到入站 Webhook 后进行，后续命令需在 Webhook 处理器中通过事件负载里的 call_control_id 发起。
拨出与呼入流程不同：拨出以 dial() 开始；呼入必须先从收到的 Webhook 中应答，之后才能执行其他命令。
需要公网可达的 Webhook 端点：没有它，通话可以连接，但应用无法驱动实时通话状态。
电话号码格式：必须为 E.164 格式（如 +13125550001），包含 + 前缀和国家代码，不能有空格、连字符或括号。
错误处理：所有 API 调用可能失败，需处理网络错误、限流（429，建议指数退避重试）、验证错误（422）、认证错误（401）、权限不足（403）、资源未找到（404）等。
不要臆造参数：官方资料强调不得编造 Telnyx 的参数、枚举、响应字段或 Webhook 字段；如需内联示例之外的字段，应查阅其 API 详情参考文档。
关于收费、价格及具体平台支持范围等信息，资料中暂未提供。

技能介绍

用途

主要能力

使用方式

适用场景

限制与注意事项