telnyx-voice-gather-python

Telnyx Voice Gather - Python 是面向 Python 开发者的技能文档，用于在 Telnyx 平台上实现语音交互中的信息采集（gather）。

用途该技能围绕电话呼叫中的输入采集展开：既能收集呼叫者的 DTMF 按键信号以构建交互式语音菜单（IVR），也能借助 AI 语音助手采集结构化信息，从而实现 AI 语音助手类应用。

安装与初始化使用 pip 安装：pip install telnyx。随后通过 API Key 初始化客户端：

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
)

文档中所有示例均假定 client 已按上述方式初始化。

主要能力

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。
Gather stop：停止当前 gather，预期 Webhook 事件为 call.gather.ended。可选参数 client_state、command_id。
Gather using AI：使用语音助手采集请求负载中定义的参数。可传入以 JSON Schema 对象描述的 parameters，语音助手会尝试收集这些信息。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 与 result。
Gather using audio：在通话中播放音频文件，直到采集到所需 DTMF 信号。可传入有效数字列表与 invalid_audio_url，后者会在每次提示开始时播放；收到 DTMF 信号时播放会被打断。
Gather using speak：将文本转为语音并在通话中播放，直到采集到所需 DTMF 信号。voice 与 payload 为必填，可传入 invalid_payload（在每次提示开始时播放）；收到 DTMF 信号时语音播报会被打断。支持 language（含多种语言枚举，如 en-US、es-MX、ja-JP、ko-KR 等）、payload_type（text、ssml）、service_level（basic、premium）等参数。
AI 助手相关操作：Start AI Assistant（在通话中启动 AI 助手，返回 conversation_id 与 result）、Stop AI Assistant（停止 AI 助手）、Add messages to AI Assistant（向 AI 助手在通话中开启的会话追加消息）。

使用方式各能力对应 Call Control API 的 POST 端点，例如：

POST /calls/{call_control_id}/actions/gather
POST /calls/{call_control_id}/actions/gather_stop
POST /calls/{call_control_id}/actions/gather_using_ai
POST /calls/{call_control_id}/actions/gather_using_audio
POST /calls/{call_control_id}/actions/gather_using_speak
POST /calls/{call_control_id}/actions/ai_assistant_start
POST /calls/{call_control_id}/actions/ai_assistant_stop
POST /calls/{call_control_id}/actions/ai_assistant_add_messages

Webhook 与验证 Telnyx 使用 Ed25519 对 Webhook 进行签名，每个请求包含 telnyx-signature-ed25519 与 telnyx-timestamp 请求头。生产环境应始终验证签名，并在处理时使用原始请求体而非已解析的 JSON：

payload = request.get_data(as_text=True)  # raw body as string
headers = dict(request.headers)
try:
    event = client.webhooks.unwrap(payload, headers=headers)
except Exception as e:
    print(f"Webhook verification failed: {e}")
    return "Invalid signature", 400

相关 Webhook 事件包括：CallAIGatherEnded、CallAIGatherMessageHistoryUpdated、CallAIGatherPartialResults、callGatherEnded。文档列出各事件的负载字段，如 record_type、event_type、id、occurred_at，以及 payload 中的 call_control_id、connection_id、call_leg_id、call_session_id、client_state、from、to、message_history、result、partial_results、digits、status 等。其中 callGatherEnded 的 status 取值包括 valid、invalid、call_hangup、cancelled、cancelled_amd、timeout；CallAIGatherEnded 的 status 为 valid、invalid。

错误处理文档建议在生产代码中处理网络错误、限流（429）、验证错误（422）与认证错误（401）。示例捕获 telnyx.APIConnectionError（网络错误，检查连通性并重试）、telnyx.RateLimitError（429，等待并使用指数退避重试，可查看 Retry-After 头确定实际延迟）、telnyx.APIStatusError（如 422 验证错误，检查必填字段与格式）。常见错误码：401 无效 API Key、403 权限不足、404 资源不存在、422 验证错误、429 限流。

适用场景可用于构建交互式语音菜单、按键采集流程、播放音频或 TTS 提示并等待按键，以及基于 AI 语音助手的语音信息采集与 AI 语音助手对话。

限制与暂未提供的信息文档未说明具体收费、价格、配额、可用区域或性能指标，这些信息暂未提供。使用 gather 前必须先执行 Answer 命令。

技能介绍