用途:这是 Telnyx 面向 Ruby 的语音流媒体技能,围绕通话媒体做实时处理,包括把通话音频分流到外部目标、将媒体流推送到指定 WebSocket 地址或 Dialogflow 连接,以及发起实时语音转写,可用于实时音频分析、欺诈检测、AI 生成语音响应等场景。
主要能力:提供 Call Control 动作接口,包括启动/停止分流、启动/停止流媒体、启动/停止转写。分流请求需指定 target 或 rx、tx 属性;流媒体会把音频以 base64 编码的 RTP 负载(原始音频)封装在 JSON 中近乎实时投递;转写支持指定引擎与配置,通话挂断时自动停止,也可手动停止。
使用方式:安装 gem install telnyx,使用 require "telnyx" 后以 api_key: ENV["TELNYX_API_KEY"] 初始化 Telnyx::Client.new。调用示例:client.calls.actions.start_forking(call_control_id)、stop_forking、start_streaming、stop_streaming、start_transcription、stop_transcription,均返回 result 字符串。
Webhook 与校验:Telnyx 使用 Ed25519 签名,请求含 telnyx-signature-ed25519 与 telnyx-timestamp 头,需在生产环境校验,可用 client.webhooks.unwrap(payload, headers) 解析并验证。相关事件包括 callForkStarted、callForkStopped、callStreamingFailed、callStreamingStarted、callStreamingStopped、transcription,负载字段涵盖 call_control_id、call_leg_id、call_session_id、client_state、stream_url、stream_id、failure_reason 等。
错误处理与限制:所有 API 调用可能失败,需处理 401(密钥无效)、403(权限不足)、404(资源不存在)、422(校验错误)、429(限流,建议指数退避重试)及网络错误。具体价格、配额与完整字段说明以官方文档为准,资料未提供更多细节。