用途:在 Telnyx 通话中采集呼叫方的 DTMF 按键或语音输入,用于构建交互式语音菜单(IVR)和 AI 语音助手。对应 Ruby SDK 技能,需先安装 gem install telnyx,并以 client = Telnyx::Client.new(api_key: ENV["TELNYX_API_KEY"]) 初始化。
主要能力与接口:
- gather:采集 DTMF 信号构建菜单,可传有效数字列表,调用前须先发 Answer 命令。client.calls.actions.gather(call_control_id)。
- gather_stop:停止当前 gather,client.calls.actions.stop_gather(call_control_id)。
- gather_using_ai:按请求中 JSON Schema 描述的 parameters(必填)用语音助手采集信息,client.calls.actions.gather_using_ai("call_control_id", parameters: {...})。
- gather_using_audio:播放音频直到采集到所需 DTMF,可传 invalid_audio_url 在每次提示开头播放,收到 DTMF 时打断播放。
- gather_using_speak:TTS 播放直到采集到所需 DTMF,必填 voice、payload,可传 invalid_payload、语言等;收到 DTMF 时打断。
- AI 助手控制:add_ai_assistant_messages(向 AI 助手对话添加消息)、start_ai_assistant(启动,返回 conversation_id)、stop_ai_assistant(停止)。
用法要点:调用需 call_control_id;gather 类命令通常在 Answer 之后发起;可配置 initial_timeout_millis、inter_digit_timeout_millis、maximum_digits、minimum_digits、terminating_digit、timeout_millis、valid_digits 等参数。
Webhook:相关事件包括 CallAIGatherEnded、CallAIGatherMessageHistoryUpdated、CallAIGatherPartialResults、callGatherEnded,需自行配置 webhook URL。Telnyx 使用 Ed25519 签名,请求头含 telnyx-signature-ed25519 与 telnyx-timestamp,生产环境应校验,可用 client.webhooks.unwrap(payload, headers) 解析验证。
错误处理:需处理网络错误、429 限流、422 校验错误、401 认证错误等,限流可退避重试。
限制:部分参数与返回字段含义、默认值及价格等资料暂未提供;gather_using_ai 的 parameters 结构示例仅为占位形式,实际 schema 需按业务定义。