用途:该技能面向 Go 开发者,封装 Telnyx Voice Media 能力,在通话中播放音频、进行文本转语音并录制通话,适用于 IVR 系统、播放公告、录制对话等场景。
安装与初始化:执行 go get github.com/team-telnyx/telnyx-go,导入 github.com/team-telnyx/telnyx-go 与 option 包,使用 telnyx.NewClient 并传入 option.WithAPIKey(os.Getenv("TELNYX_API_KEY")) 初始化客户端。
主要能力:
- 播放音频:调用 StartPlayback,需 call_control_id 与 AudioURL;连续播放命令会排队。可选参数含 audio_type、cache_audio、loop、overlay、media_name、target_legs 等,overlay 启用时 target_legs 仅限 self。停止播放使用 StopPlayback,会触发 call.playback.ended 或 call.speak.ended。
- 文本转语音:调用 Speak,必填 payload 与 voice,可选 language、payload_type(text/ssml)、service_level(basic/premium)、loop、target_legs、voice_settings 等,返回 result,触发 call.speak.started 与 call.speak.ended。
- 录制:StartRecording 必填 format 与 channels,可选 max_length、play_beep、recording_track、transcription、transcription_engine(如 deepgram/nova-3)、transcription_language、说话人分离等;StopRecording 停止录制;PauseRecording 与 ResumeRecording 暂停和恢复。录制会触发 call.recording.saved、call.recording.transcription.saved、call.recording.error 等。
Webhook:Telnyx 使用 Ed25519 签名,请求含 telnyx-signature-ed25519 与 telnyx-timestamp 头。生产环境应用 client.Webhooks.Unwrap(body, r.Header) 验证签名后再处理事件,如 callPlaybackStarted、callPlaybackEnded、callRecordingSaved、callRecordingTranscriptionSaved、callSpeakStarted、callSpeakEnded 等。
错误处理:所有 API 调用可能因网络、限流(429)、校验(422)或认证(401)失败,生产代码应处理错误并按状态码重试或提示。常见错误码:401 无效 API Key、403 权限不足、404 资源不存在、422 校验错误、429 限流。
限制:需有效 TELNYX_API_KEY 与可用的 Call Control 应用;部分参数为枚举值,须按文档取值;其它收费、价格与平台细节暂未提供。