用途
Telnyx Voice Advanced - curl 是一套面向 Telnyx 语音呼叫控制 REST API 的技能文档，演示如何用 curl 命令在已建立的通话上执行高级控制操作。它适用于需要通过命令行或脚本对语音通话做精细控制的开发场景，例如在呼叫进行中发送按键、开启录音、抑制背景噪声、接入 AI 对话或切换监听角色。
主要能力
资料列出的接口操作包括：
- 加入 AI 助手会话：
POST /calls/{call_control_id}/actions/ai_assistant_join，必填 conversation_id 与 participant，可选 client_state、command_id。 - 更新客户端状态：
PUT /calls/{call_control_id}/actions/client_state_update，必填 client_state。 - 启动 Conversation Relay：
POST /calls/{call_control_id}/actions/conversation_relay_start，将通话音频接入自有 WebSocket，由 Telnyx 负责语音识别与文本转语音。资料注明同一通话上同一时间只能有一个 AI Assistant 或 Conversation Relay 会话处于活动状态。 - 停止 Conversation Relay：
POST /calls/{call_control_id}/actions/conversation_relay_stop。 - 发送 DTMF：
POST /calls/{call_control_id}/actions/send_dtmf，必填 digits，可选 duration_millis。该命令没有关联 Webhook。 - SIPREC 启停：
POST /calls/{call_control_id}/actions/siprec_start与siprec_stop，可配置 connector_name、secure、session_timeout_secs、sip_transport、siprec_track 等。 - 噪声抑制（BETA）：
POST /calls/{call_control_id}/actions/suppression_start与suppression_stop，可选 direction 与 noise_suppression_engine（如 Denoiser、DeepFilterNet、Krisp、AiCoustics 等）。 - 切换主管角色：
POST /calls/{call_control_id}/actions/switch_supervisor_role，必填 role，用于桥接通话中在活动通话期间切换不同的主管模式。
安装与鉴权
curl 在 macOS、Linux 与 Windows 10+ 上通常已预装。鉴权通过环境变量设置：
export TELNYX_API_KEY="YOUR_API_KEY_HERE"
所有示例均使用 Authorization: Bearer $TELNYX_API_KEY 与 Content-Type: application/json，请求基址为 https://api.telnyx.com/v2。
错误处理
资料建议在生产代码中始终检查 HTTP 状态码。常见错误码：401（API key 无效）、403（权限不足）、404（资源不存在）、422（校验错误，检查字段格式）、429（限流，建议使用指数退避重试）。示例脚本通过 curl -s -w "\n%{http_code}" 分离响应体与状态码，并用 case 分支处理。
Webhook
Telnyx 使用 Ed25519 对 Webhook 签名，每个请求包含 telnyx-signature-ed25519 与 telnyx-timestamp 头。资料强调必须验证签名，并建议拒绝时间戳超过 5 分钟的请求以防重放。公钥可在 Telnyx Portal 的 Account Settings > Keys & Credentials 获取，验证时应使用对应语言的 Telnyx SDK（client.webhooks.unwrap）。端点须在 2 秒内返回 2xx，否则 Telnyx 会重试（最多 3 次）；可在 Portal 配置故障转移 URL。
相关资料列出的 Webhook 事件包括：callConversationEnded、callConversationInsightsGenerated、callDtmfReceived、callMachineDetectionEnded、callMachineGreetingEnded、callMachinePremiumDetectionEnded、callMachinePremiumGreetingEnded、callReferCompleted、callReferFailed、callReferStarted、callSiprecFailed、callSiprecStarted、callSiprecStopped。以 callConversationEnded 为例，其 payload 字段包含 record_type、event_type、id、occurred_at、created_at，以及 assistant_id、call_control_id、connection_id、call_leg_id、call_session_id、client_state、calling_party_type、conversation_id、duration_sec、reason、from、to、llm_model、stt_model、tts_provider、tts_model_id、tts_voice_id 等；callDtmfReceived 包含 digit 字段；callMachineDetectionEnded 的 result 为 human、machine、not_sure 之一。
适用场景与限制
适用场景为需要在现有通话上做进阶控制的集成开发，如呼叫中心录音、AI 语音代理、自动按键交互、座席监听切换等。限制方面：噪声抑制标注为 BETA；Conversation Relay 与 AI Assistant 在同一通话上互斥；部分命令（如发送 DTMF）不产生 Webhook；Webhook 需自行实现签名校验与快速响应。资料未提供具体价格、计费方式或平台可用性细节，相关内容暂未提供。