呼叫中心 API 接入准备指南：坐席、任务与事件

坐席组、基础设置与呼入响铃

呼叫中心对接应先建立业务组织与坐席组的对应关系。新增坐席组前确定名称、用途和管理权限；查询列表时保留稳定的组标识。修改名称不应让历史通话记录失去归属，删除组前则需要检查关联坐席、任务与保留策略。

查询或编辑坐席组基础设置时，先取得当前版本并核对变更范围，避免一个系统覆盖另一个系统的设置。上传、替换或删除呼入响铃应核对音频格式、时长、音量和使用权限，并在实际呼入流程验证播放结果。

获取坐席组最大创建话机数用于容量规划，不能据此承诺固定并发能力。还应分别确认账户额度、坐席数量、话机分配和实际通话限制。

核对要点

• 为新增、查询、改名和删除准备权限与审计记录。
• 基础设置与响铃变更先在小范围验证。
• 核对容量不足、关联未清理和并发修改的行为。

组长管理与批处理

新增组长时，明确其负责的坐席组和可访问的数据范围。查询组长列表应处理分页、停用账户和重复授权；编辑组长时复核角色变化是否会影响进行中的任务和报表访问。

组长批处理不能只依据整批返回结果认定全部完成。保留每条操作的对象标识和结果，对部分失败给出可重试清单。权限减少后要确认已有会话和后台访问如何失效。

核对要点

• 限制跨组数据访问，使用最小必要权限。
• 核对批处理的部分成功、重复执行和撤销条件。
• 人员变动时同步停用不再需要的授权。

坐席创建、优先级与有效通话定义

批量创建坐席前检查人员与业务标识是否唯一，确认创建成功后如何发放凭证。查询坐席列表、修改坐席和坐席批处理应围绕稳定标识操作，并区分暂时离线、停用和删除。

设置坐席优先级时，要验证分配策略是否符合业务规则，观察是否出现个别坐席长期得不到任务。有效通话定义影响统计口径，需明确计时起点、时长阈值、接通条件与版本生效时间。

不要用报表中的“有效通话”直接替代客户问题解决率。发生规则变化时保留旧口径，避免跨时间报表在没有说明的情况下被比较。

核对要点

• 测试重复创建、无效用户和部分失败。
• 修改优先级后检查真实任务分配。
• 对有效通话规则建立版本和验收样例。

中继配置、查询与批量启停

新增中继前，由项目确认网络路径、认证方式、允许的来源地址、号码格式和路由规则。查询与编辑中继配置应限制敏感字段展示；测试配置与生产配置分开保存。

删除中继、批量启用或批量禁用中继可能影响正在使用的呼叫任务。操作前检查关联任务与替代路由，安排观察窗口，并确认已建立通话和新呼叫分别如何处理。

中继可连通不代表语音质量达标。验收应分别检查呼叫建立、双向音频、DTMF、挂断原因与异常恢复；实际支持项和网络要求以项目确认资料为准。

核对要点

• 限制中继配置权限，不在日志中记录密码。
• 批量操作逐项记录结果并保留恢复步骤。
• 覆盖无法注册、无音频、单向音频和路由失效。

预览式与群呼转坐席任务的完整生命周期

查询预览式任务列表、任务详情和任务动态表头时，确认筛选条件、分页规则、字段含义和权限范围。动态表头不能直接作为可信页面代码使用；展示字段应经过白名单或安全编码。

上传呼叫号码 EXCEL 前核对列定义、号码格式、去重规则、文件大小和数据使用权限。新增或重呼去重提交任务时，区分文件去重、任务去重与业务请求幂等，避免将同一批号码重复触达。

启用、暂停、取消、编辑群呼转坐席任务以及修改任务状态，都应有明确状态机。确认哪些字段可在运行中修改、暂停是否阻止新呼叫、取消是否可恢复，以及任务状态与进行中通话是否一致。

核对要点

• 先上传少量授权测试号码验证列映射。
• 检查创建、启动、暂停、重呼、取消的状态转换。
• 对重复提交、任务冲突和部分失败设置可追溯记录。

通话记录、主动推送与坐席振铃事件

查询通话记录列表时，用稳定通话标识关联坐席、任务和业务记录，并核对时区、分页、挂断原因与计时字段。记录生成时间和通话发生时间可能不同，按时间检索要预留补查窗口。

通话记录主动推送与坐席振铃事件主动推送描述不同阶段。振铃不等于接通，通话结束也不等于业务完成。接收端要按文档验证事件，记录来源并去重，允许事件延迟和乱序。

如果查询记录与事件推送不一致，保留原始时间线并按约定的最终状态来源对账。不要把客户端收到事件的时间当作服务侧事件的发生时间。

核对要点

• 测试重复、乱序、延迟和事件丢失后的补查。
• 关联呼叫标识、坐席标识、任务标识与内部业务号。
• 区分振铃、接通、结束和业务处理完成。

权限、容量与上线验收

验收应覆盖组织权限、配置变更、任务运行和事件闭环。先用少量坐席与测试任务确认完整流程，再观察高负载条件下的排队、限流和失败恢复。没有经过实际验证，不对并发量或通话质量做确定承诺。

上线资料应包括数据保留周期、故障联系人、暂停入口、权限回收和回滚步骤。故障排查提供脱敏时间线与任务或通话标识，不提供完整客户名单、账号密码或不必要的录音原件。

核对要点

• 明确报表口径、容量边界和录音访问权限。
• 变更中继或任务策略后重新执行关键验收。
• 记录每次上线配置和恢复方案。