用途:该技能针对 Ruby 开发者在 Telnyx 通话(Call Control)中处理语音媒体,包括播放音频文件、文本转语音播报、以及录制通话,适合构建 IVR 系统、播放公告或录制对话。
安装与初始化:gem install telnyx;然后 require "telnyx" 并创建 client = Telnyx::Client.new(api_key: ENV["TELNYX_API_KEY"])。所有示例均假定 client 已初始化。
主要能力(均通过 Calls Actions 发起,返回 result 字符串):
- 播放音频:start_playback,POST /calls/{call_control_id}/actions/playback_start;支持 mp3、wav 等参数。连续调用会排队播放。overlay 开启时 target_legs 仅限 self。
- 停止播放:stop_playback。
- 文本转语音:speak,必填 payload、voice;支持语言、SSML、音色、循环等。连续调用同样排队。
- 录制控制:start_recording(必填 format、channels)、stop_recording、pause_recording、resume_recording;录制可携带转写相关参数(transcription、engine、language 等)。
Webhook:Telnyx 使用 Ed25519 签名,请求含 telnyx-signature-ed25519 与 telnyx-timestamp 头,生产环境应使用 client.webhooks.unwrap(payload, headers) 校验,校验需使用原始请求体。事件包括 call.playback.started/ended、call.speak.started/ended、call.recording.saved/error、call.recording.transcription.saved 等,payload 携带 call_control_id、call_leg_id、call_session_id、client_state、status 等字段。
错误处理:需捕获网络错误、429 限流(建议指数退避并参考 Retry-After)、422 校验错误、401/403 认证与权限错误等。
限制:资料未说明收费、价格与配额;未提供完整 API 参数明细以外的业务规则,具体速率与合规要求暂未提供。