telnyx-voice-gather-javascript

Telnyx Voice Gather - JavaScript 是面向 JavaScript/Node.js 开发者的通话采集技能，基于 Telnyx 官方 SDK（telnyx@6.74.2），用于从通话中采集来电者的 DTMF 按键输入或语音信息，进而构建交互式语音菜单和 AI 语音助手。

一、用途该技能主要用于在电话通话中收集用户输入：既支持传统的 DTMF 数字按键采集（用于 IVR 交互式语音菜单），也支持通过语音助手以对话方式采集结构化信息（如确认为 JSON Schema 定义的字段），适用于需要电话交互、语音导航或语音信息采集的场景。

二、安装与初始化安装命令：npm install telnyx@6.74.2 初始化方式： import Telnyx from 'telnyx'; const client = new Telnyx({ apiKey: process.env['TELNYX_API_KEY'], }); 文档说明该 apiKey 为默认方式，可省略。

三、错误处理所有 API 调用可能因网络错误、限流（429）、校验错误（422）或认证错误（401）失败。文档建议在生产代码中统一捕获错误，并区分处理：APIConnectionError（网络错误，检查连接并重试）、RateLimitError（429，根据 retry-after 头等待并以指数退避重试）、APIError（输出状态码与消息，其中 422 需检查必填字段与格式）。常见错误码：401 无效 API 密钥，403 权限不足，404 资源未找到，422 校验错误，429 限流。

四、主要能力

Gather（采集 DTMF）：POST /calls/{call_control_id}/actions/gather。用于采集 DTMF 信号构建交互式菜单，可传入有效数字列表。文档强调必须先执行 Answer 命令再执行 gather。可选参数包括 client_state、command_id、gather_id、initial_timeout_millis、inter_digit_timeout_millis、maximum_digits、minimum_digits、terminating_digit、timeout_millis、valid_digits。返回 result（string）。
Gather stop：POST /calls/{call_control_id}/actions/gather_stop，停止当前 gather，预期 Webhook 为 call.gather.ended。可选参数 client_state、command_id。返回 result。
Gather using AI：POST /calls/{call_control_id}/actions/gather_using_ai，使用语音助手采集请求载荷中定义的参数。可传入 JSON Schema 对象描述参数，语音助手会尝试采集这些信息。parameters 为必填。可选参数包括 assistant、client_state、command_id、gather_ended_speech、greeting、interruption_settings、language、message_history、send_message_history_updates、send_partial_results、transcription、user_response_timeout_ms、voice、voice_settings。返回 conversation_id（uuid）与 result。
Gather using audio：POST /calls/{call_control_id}/actions/gather_using_audio，在通话中播放音频文件，直到采集到所需 DTMF 信号。可传入有效数字列表以及 invalid_audio_url，后者会在每次提示开始时播放；收到 DTMF 信号时播放会被打断。可选参数包括 audio_url、client_state、command_id、inter_digit_timeout_millis、invalid_audio_url、invalid_media_name、maximum_digits、maximum_tries、media_name、minimum_digits、terminating_digit、timeout_millis、valid_digits。返回 result。
Gather using speak：POST /calls/{call_control_id}/actions/gather_using_speak，将文本转换为语音并在通话中播放，直到采集到所需 DTMF 信号。可传入有效数字列表以及 invalid_payload，后者会在每次提示开始时播放；收到 DTMF 信号时语音会被打断。必填参数为 voice、payload。可选参数包括 client_state、command_id、inter_digit_timeout_millis、invalid_payload、language（枚举含 arb、cmn-CN、cy-GB、da-DK、de-DE、en-AU、en-GB、en-GB-WLS、en-IN、en-US、es-ES、es-MX、es-US、fr-CA、fr-FR、hi-IN、is-IS、it-IT、ja-JP、ko-KR、nb-NO、nl-NL、pl-PL、pt-BR、pt-PT、ro-RO、ru-RU、sv-SE、tr-TR）、maximum_digits、maximum_tries、minimum_digits、payload_type（text、ssml）、service_level（basic、premium）、terminating_digit、timeout_millis、valid_digits、voice_settings。返回 result。
AI 助手管理：
- 添加消息：POST /calls/{call_control_id}/actions/ai_assistant_add_messages，向 AI 助手在该通话中发起的会话添加消息。可选 client_state、command_id、messages。返回 result。
- 启动：POST /calls/{call_control_id}/actions/ai_assistant_start，在通话中启动 AI 助手，预期 Webhook 为 call.conversation.ended 与 call.conversation_insights.generated。可选参数包括 assistant、client_state、command_id、greeting、interruption_settings、message_history、participants、send_message_history_updates、transcription、voice、voice_settings。返回 conversation_id（uuid）与 result。
- 停止：POST /calls/{call_control_id}/actions/ai_assistant_stop，停止通话中的 AI 助手。可选 client_state、command_id。返回 result。

五、Webhook Telnyx 使用 Ed25519 对 Webhook 签名，每个请求包含 telnyx-signature-ed25519 和 telnyx-timestamp 头。文档建议在生产环境中始终校验签名，并使用原始请求体（如 Express 的 express.raw）交给 client.webhooks.unwrap() 验证；验证失败返回 400。

技能介绍