用途
本技能用于在 JavaScript 环境中集成 Telnyx 的语音实时处理能力，主要面向需要对通话音频做实时分析、AI 语音交互或实时转写的场景。官方描述指出，它可以实时流式传输通话音频、将媒体分叉到外部目标，并实时转写语音，适用于实时分析与 AI 集成。
安装与初始化
安装命令为 npm install telnyx。初始化方式为 import Telnyx from 'telnyx';，然后使用 new Telnyx({ apiKey: process.env['TELNYX_API_KEY'] }) 创建客户端。官方示例说明该 apiKey 为默认项，可以省略。
主要能力
- 呼叫分叉（Forking）：通过
POST /calls/{call_control_id}/actions/fork_start和fork_stop启停，可将通话媒体实时流式传输到指定目标。请求需指定 target 属性，或 rx 与 tx 属性。可用于欺诈检测、AI 生成音频响应等用途。 - 流式传输（Streaming）：通过
streaming_start和streaming_stop启停。可将媒体以近实时方式发送到指定 WebSocket 地址或 Dialogflow 连接。音频以 base64 编码的 RTP 负载（原始音频）封装在 JSON 负载中传输。支持配置 stream_bidirectional_codec、stream_bidirectional_mode、stream_bidirectional_sampling_rate、stream_bidirectional_target_legs、stream_codec、stream_track、stream_url、stream_auth_token、enable_dialogflow、dialogflow_config、custom_parameters 等可选参数。 - 实时转写（Transcription）：通过
transcription_start和transcription_stop启停。转写会在通话挂断时停止，也可主动通过停止命令终止。可配置 transcription_engine（Google、Telnyx、Deepgram、Azure、A、B）、transcription_engine_config、transcription_tracks 等可选参数。
上述三种能力的调用示例均形如 await client.calls.actions.xxx('v3:...')，返回值为 result（字符串）。
使用方式与 Webhook
相关操作会产生 Webhook 事件，需配置 Webhook URL 接收。事件包括：callForkStarted、callForkStopped、callStreamingFailed、callStreamingStarted、callStreamingStopped、transcription。所有 Webhook 携带 telnyx-timestamp 与 telnyx-signature-ed25519 头部，采用 Ed25519 签名。官方要求在 Webhook 处理器中使用原始 body（而非已解析的 JSON）调用 client.webhooks.unwrap(req.body.toString(), { headers: req.headers }) 验证签名，验证失败应返回 400。Webhook 负载字段包含 record_type、event_type、id、occurred_at，以及 payload 中的 connection_id、call_control_id、call_leg_id、call_session_id、client_state 等信息；流式相关事件还含 stream_url、stream_type、stream_id、failure_reason 等字段。
错误处理
所有 API 调用都可能因网络错误、速率限制（429）、验证错误（422）或认证错误（401）失败。官方示例展示了捕获 Telnyx.APIConnectionError、Telnyx.RateLimitError（可读取 err.headers 中的 retry-after 后进行指数退避重试）与 Telnyx.APIError（可读取 err.status 与 err.message）的处理方式。常见错误码含义：401 无效 API key、403 权限不足、404 资源不存在、422 验证错误、429 速率限制。
适用场景与限制
适用场景包括实时音频分析、欺诈检测、AI 语音响应生成、实时语音转写及与 AI 服务集成。限制方面，资料仅说明转写会在挂断时停止，并要求生产环境验证 Webhook 签名；关于价格、平台范围、并发上限、音频质量等更多细节暂未提供。