语音 API 接入准备指南：文件、话机、群呼与录音

上传与查询语音文件、文件语音和 TTS

语音 API 接入首先区分预先录制的文件语音与文本转语音。上传语音文件前确认编码、采样率、声道、时长、音量及使用权限；查询语音文件时保留稳定标识，避免仅用文件名关联业务。

发送文件语音消息前验证文件可用性和目标语言。发送 TTS 语音消息需测试文本清洗、变量替换、数字和专有名词读法，并通过实际播放验收。听感、内容合规和可用语言不能只依据一次成功返回来确认。

涉及验证码时，明确有效期、重复请求处理和接听失败后的业务流程。不同消息类型的重试次数、触达时段和收件人授权方式要分别设计，不以提高重试频率替代问题排查。

核对要点

• 用小样本检查格式、发音和变量内容。
• 核对文件失效、审核未通过和语言不支持的处理。
• 确认音频和文本的保存期限及访问权限。

创建、查询、重置话机密码与调用话机

创建话机前确认所属账户或坐席组、凭证发放方式和允许使用的网络。查询话机只展示必要信息；重置话机密码应有权限校验、审计和安全交付渠道，不通过普通日志或群聊传递。

调用话机时，将话机、坐席和内部业务记录关联。确认请求受理、振铃、接通和挂断各阶段的标识及状态。密码重置或话机停用后，还需验证已有注册和进行中通话的处理方式。

核对要点

• 区分创建成功、注册成功与实际可通话。
• 测试重复创建、无权限重置和凭证失效。
• 保留可追溯的操作记录，不保留明文密码。

话机、群呼与验证码记录的单条和批量查询

话机记录单条查询和批量查询用于业务定位与对账。群呼、验证码记录的单条或批量查询也应保留请求与服务返回标识，明确筛选字段、分页顺序、时区和数据保留范围。

同一通话可能在初次查询后继续更新。业务侧应保存最后核对时间，并根据最终状态条件补查未完成记录。不要把“记录不存在”直接视为“从未发起”，也不要把“已提交”误当作“已接通”。

核对要点

• 测试跨页、跨日、延迟入库和重复记录。
• 将内部业务号与话机或语音任务标识对应。
• 对未知状态设置补查与人工核对条件。

语音群呼任务创建、修改与启停

创建语音群呼任务前，确认号码来源、用途、授权依据、发送时段和频率上限。选择语音文件或 TTS 内容后，用少量测试号码验证内容和流程，不直接从测试任务扩大到全部名单。

查询群呼任务列表与详情时，核对任务状态、号码数量、结果统计和分页条件。修改、重呼、启动、暂停及取消任务需明确状态约束，尤其要验证暂停或取消后是否仍有已发起的呼叫在继续。

获取坐席组信息可用于确认任务与人工服务的关联条件。相关容量、可用坐席和转接能力须分别验证，不能只根据组存在就认为任务能够顺利转接。

核对要点

• 覆盖创建、查询、修改、重呼、启动、暂停和取消。
• 验证重复提交、状态冲突与部分处理失败。
• 为异常触达设置立即暂停和调查流程。

语音状态报告推送与结果核对

语音状态报告推送需要校验来源并记录稳定事件标识。接收端先可靠保存，再返回约定应答；重复、乱序和延迟事件应得到一致处理，避免任务计数在重复推送后被放大。

状态名称与挂断原因以项目资料为准。分别解释请求受理、振铃、接通、播放完成与业务成功，不将其中一个状态替代其他阶段。推送不可达时，使用已约定的查询方式恢复缺失记录。

核对要点

• 测试接收超时、重复推送、错误签名和接收端重启。
• 保留服务侧发生时间和本站接收时间。
• 用最终记录核对任务汇总，而不只统计事件条数。

录音文件地址、文件流与批量删除

获取通话录音文件地址或 CC 录音文件流前，确认录音是否启用、适用的告知授权要求和访问范围。下载地址可能有时效性，不能作为永久公开链接嵌入网页；文件流也需要鉴权、限速和访问审计。

录音文件批量删除前核对业务留存与争议处理要求，确认删除对象、备份处理和不可恢复性。先在小范围验证，再执行批量操作；失败记录与仍可访问的副本应单独跟进。

录音资料应按最小必要原则保存，限制内部下载与转发。故障排查优先使用通话标识和脱敏描述，只有确有必要且具备权限时才提供录音片段。

核对要点

• 确认短期下载链接、权限过期和删除后的行为。
• 建立录音保留周期和访问审计。
• 批量删除逐项记录结果并验证副本处理。

语音联调与上线验收

语音验收需要真实听取并记录结果，覆盖双向音频、音量、延迟、数字播报、DTMF 和挂断原因中项目实际使用的部分。终端、地区和网络不同可能产生不同表现，要保留测试条件。

上线前确定预算、触达上限、失败告警和暂停入口。变更文件、TTS 内容、话机凭证或任务策略后复测关键链路，保留可执行的回滚方式。

核对要点

• 用授权测试号码验证完整结果闭环。
• 明确故障负责人和恢复步骤。
• 根据实际监控逐步放量。