用途
Telnyx Voice Advanced - Ruby 是一个基于 Telnyx Ruby SDK 的语音通话高级控制技能，面向需要在 Ruby 应用中对接 Telnyx Call Control API 的开发者，提供超越基础通话操作的进阶能力。
主要能力
该技能覆盖以下通话控制能力：
- 发送 DTMF：从当前通话腿发送 DTMF 按键音，可被对端听到（POST /calls/{call_control_id}/actions/send_dtmf，必填 digits，可选 client_state、command_id、duration_millis）。该命令没有关联的 Webhook。
- SIPREC 录音：启动与停止 SIPREC 会话（siprec_start / siprec_stop），用于将通话录音发送到已配置的 SIPREC 连接器 SRS。启动时可配置 connector_name、secure、session_timeout_secs、sip_transport、siprec_track 等；相关 Webhook 包括 siprec.started、siprec.stopped、siprec.failed。
- 噪声抑制（BETA）：启动与停止通话降噪（suppression_start / suppression_stop），可选择方向（inbound、outbound、both）与降噪引擎（如 Denoiser、DeepFilterNet、Krisp 等）。
- 客户端状态更新：更新通话的 client_state（PUT /calls/{call_control_id}/actions/client_state_update）。
- 主管角色切换：在桥接通话中切换主管角色（switch_supervisor_role），可在通话进行中切换不同主管模式。
- AI 助手会话加入：向正在运行的 AI 助手会话中加入额外通话腿（ai_assistant_join，必填 conversation_id 与 participant）。
- Conversation Relay：在活动通话上启动或停止 Conversation Relay 会话，将通话音频连接到你的 WebSocket，由应用与呼叫方实时交换消息，语音识别与文本转语音由 Telnyx 处理。同一通话同一时间只能有一个 AI Assistant 或 Conversation Relay 会话处于活动状态。
使用方式
安装：
gem install telnyx
初始化客户端：
require "telnyx"
client = Telnyx::Client.new( api_key: ENV["TELNYX_API_KEY"], )
所有示例均假设 client 已按上述方式初始化。
错误处理
所有 API 调用都可能因网络错误、限流（429）、校验错误（422）或鉴权错误（401）而失败，生产代码应始终处理错误。常见错误码：401 API Key 无效、403 权限不足、404 资源未找到、422 校验错误、429 触发限流（建议使用指数退避重试，并检查 Retry-After 头）。
Webhook 与事件
Webhook 使用 Ed25519 签名，请求头包含 telnyx-signature-ed25519 与 telnyx-timestamp，生产环境应始终验证签名，可使用 client.webhooks.unwrap() 完成验证。相关事件包括：callConversationEnded、callConversationInsightsGenerated、callDtmfReceived、callMachineDetectionEnded、callMachineGreetingEnded、callMachinePremiumDetectionEnded、callMachinePremiumGreetingEnded、callReferCompleted、callReferFailed、callReferStarted、callSiprecFailed、callSiprecStarted、callSiprecStopped 等，各事件包含 record_type、event_type、id、occurred_at 以及 payload 字段（如 call_control_id、connection_id、call_leg_id、call_session_id、client_state 等）。
适用场景
适用于需要在 Ruby 应用中实现高级语音控制的场景，例如 IVR 与按键交互、通话合规录音、通话降噪、坐席主管监听与切换、以及将通话音频接入实时 AI 对话（Conversation Relay）等。
限制
降噪功能标注为 BETA。同一通话同一时间只能有一个 AI Assistant 或 Conversation Relay 会话处于活动状态。详细的价格、配额与其他平台限制在本资料中暂未提供。