通话集成
配置嵌入式通话、通话事件订阅规则与集成测试台
简述
通话集成 用于把 OpenDesk 呼叫能力接入第三方系统，并把通话过程事件推送给外部服务。模块包含两个子功能：
| 子功能 | 说明 |
|---|---|
| 嵌入式通话 | 将 OpenDesk 软电话嵌入 CRM、业务后台等第三方 Web 页面 |
| 事件订阅 | 按通话方向、来源和事件类型配置推送规则 |
拥有 管理嵌入式通话 或 管理通话事件订阅 任一权限时，可看到 通话集成 菜单；进入后仅展示当前账号有权限的子功能。
功能位置
在管理后台侧边栏 呼叫中心 → 通话集成 打开。页面顶部可在 嵌入式通话 与 事件订阅 之间切换。
推荐接入流程
第三方系统接入嵌入式通话时，建议按下面顺序联调：
- 管理员创建嵌入式通话集成，配置客户系统页面的 Origin，并将 Integration key 与 Server secret 交给客户后端。
- 确认坐席具备嵌入式通话和外呼权限，且已配置可用呼叫设备与外显号码。
- 超级管理员在 全局设置 → 事件订阅 中创建 Webhook Endpoint，并保存 Webhook Secret。
- 管理员在 通话集成 → 事件订阅 中创建通话事件规则，选择方向、来源和需要推送的事件。
- 客户系统完成前端嵌入、服务端签名、Webhook 接收和录音补拉后，通过集成测试台或真实测试通话验证。
配置与规则
嵌入式通话
嵌入式通话用于在客户自有系统中加载 OpenDesk 软电话。管理员可创建集成，配置允许加载软电话的页面来源，并把 Integration key 与 Server secret 交给客户后端。
| 配置项 | 说明 |
|---|---|
| 集成名称 | 用于区分不同客户系统或不同环境 |
| 允许 Origin | 第三方页面的精确来源，例如 https://crm.example.com |
| 启用状态 | 关闭后不再签发新的嵌入式通话会话 |
保存成功后，Server secret 只完整展示一次；后续可轮换 Secret。列表中可搜索名称、Key 或来源，并查看集成状态。
坐席要求
嵌入式通话签名时需要指定坐席的用户名或邮箱。该坐席需要具备嵌入式通话和外呼相关权限，并已配置可用呼叫设备与外显号码。
嵌入式软电话能力
嵌入到第三方页面后，坐席可在软电话中选择外显号码、拨打客户号码，并使用通话控制能力。通话中也可按权限执行 发短信、邀请满意度调查 等操作；这些操作与 OpenDesk 呼叫中心工作台中的通话能力保持一致。
客户系统也可以通过 SDK 发起外呼，并在拨号时传入业务上下文，例如订单号、工单号、会员编号等。业务上下文会随通话事件回调返回，便于客户系统把通话结果回写到自己的业务记录。
事件订阅规则
事件订阅规则决定哪些通话事件会推送到哪个订阅接口。创建规则时需要选择：
| 配置项 | 说明 |
|---|---|
| 规则名称 | 租户内唯一，便于识别用途 |
| 订阅接口 | 来自 全局设置 → 事件订阅 的 Webhook Endpoint |
| 通话方向 | 呼入、外呼 |
| 通话来源 | 呼入、坐席手动外呼、嵌入式通话、个人自动外呼、人工外呼任务、自动外呼等 |
| 事件类型 | 通话生命周期、排队与人工服务、录音、满意度等事件 |
每个租户最多创建 10 条通话事件订阅规则。规则停用后不再推送新的通话事件；重新启用不会补发停用期间的事件。
如果只需要最终结果，通常选择 通话已结束 即可；如果还需要记录接通、转接、录音或满意度过程，应同时勾选对应事件。规则只影响保存之后新发生的通话，已经产生的通话不会按新规则补发。
可订阅事件
| 事件分组 | 事件 |
|---|---|
| 通话生命周期 | 通话已创建、客户已接通、通话已结束 |
| 排队与人工服务 | 已进入队列、坐席已接入、坐席已离开、转接已完成 |
| 录音 | 录音已完成、录音失败 |
| 满意度 | 满意度已完成 |
事件投递采用 Webhook 方式。客户服务器收到事件后，建议用事件正文中的 id 去重，用 subject 或 data.call.public_id 关联同一通电话，用 data.sequence 判断同一通电话内的事件顺序。
事件投递的详细字段、典型回调案例、录音下载地址与补拉方式，见 Open API → 通话事件与录音 API。
集成测试台
在 嵌入式通话 列表说明文字右侧可打开 集成测试台。测试台用于联调嵌入式通话和通话事件订阅：
- 填写嵌入集成 Key、嵌入集成密钥、坐席用户名或邮箱。
- 加载嵌入式通话组件，测试拨号或只填入拨号盘。
- 复制测试台生成的 Webhook 地址，在全局事件订阅与通话事件规则中配置。
- 查看按通话分组的事件到达情况。
- 使用 API Key 查询通话录音，或重新签发录音下载地址。
测试台配置仅保存在当前浏览器中，适合实施、开发或客户技术团队联调使用。
注意事项
- 事件规则只影响规则保存之后的新通话；已经生成或正在重试的投递会继续按原配置完成。
- 一个订阅接口同一时间只能被一条通话事件规则使用，避免重复推送。
- 录音下载地址有有效期，接收方应及时转存；过期后使用 API Key 重新获取。
- 嵌入式通话页面的浏览器事件只代表前端组件状态，服务端对账请以事件订阅或通话记录为准。
与其他功能的关系
- 事件订阅（全局设置）：维护 Webhook Endpoint 与 Secret。
- API Key：用于录音下载地址过期后的重新签发。
- 通话记录：可按通话公开标识或号码核对事件对应的真实通话。
- 呼叫中心工作台：坐席权限、设备与外显号码会影响嵌入式通话是否可拨出。
业务场景示例
在 CRM 中嵌入软电话并接收结果
角色与目标： 企业希望坐席在 CRM 页面直接外呼，并把通话结果回写 CRM。
系统配置： 管理员在 嵌入式通话 新建集成，配置 CRM 的 Origin；超管在 全局设置 → 事件订阅 新建 CRM Webhook；管理员再在 事件订阅 中配置来源为 嵌入式通话、方向为 外呼 的规则。
场景效果： 坐席在 CRM 内拨打电话，OpenDesk 负责通话能力；CRM 通过事件订阅收到通话创建、客户接通、坐席接入、通话结束、录音完成等事件，用于更新业务单状态、保存通话结果并归档录音。
通过业务上下文关联订单或工单
角色与目标： 客户系统希望把每通电话准确关联到自己的订单、工单或会员档案。
系统配置： 客户系统通过嵌入式通话 SDK 发起外呼时传入业务上下文，例如订单号、工单号或会员 ID。
场景效果： OpenDesk 在通话事件回调中返回外部上下文；客户系统收到 call.ended 后，可根据通话结果、挂断原因、通话时长和业务上下文，自动回写对应业务记录。
接收录音并在过期后补拉
角色与目标： 企业希望将通话录音同步到自己的质检、合规或客户档案系统。
系统配置： 通话事件规则勾选录音事件，客户服务器接收 call.recording.completed 后及时下载录音；同时准备 API Key，用于录音下载地址过期后重新签发。
场景效果： 客户系统可在录音完成后自动转存文件；如果临时下载地址已失效，可根据回调中的通话公开标识或录音公开标识重新获取下载地址。