邀请功能 — 方案三交互原型

WebSocket + 应用消息双通道架构 | 在现有一对一对话上扩展多人参与
0. 架构概览
1. 一对一会话中
2. 点击邀请
3. 选人界面
4. 历史共享
5. 确认邀请
6. 被邀请方通知
7. 加入会话
8. 多人会话

方案三核心架构

在现有 WebSocket 双通道 架构上扩展,不引入群聊概念。后端维护 conversation.participants 数组,所有参与者共享同一个 WebSocket 会话通道。

架构流程图
H5 员工端 发起者 WebSocket 后端 FastAPI + Redis participants[] 企微 API 应用消息推送 通讯录 坐席工作台 WebSocket 接单+邀请 H5 被邀请人 企微消息→H5 WebSocket WS 双向 WS 双向 邀请通知 应用消息→H5→WS
关键区别:不创建企微群聊,所有参与者通过 H5+WebSocket 接入同一个后端 conversation。企微应用消息仅用于「通知被邀请人」和「断连降级推送」。

场景:坐席正在与用户一对一对话

用户「张三」遇到 VPN 问题,坐席「小李」正在处理。对话过程中发现需要网络安全组同事「王工」协助排查。

坐席工作台 — 会话区
张三
IT研发部 · 高级开发工程师
会话中
VPN 连接不上,提示证书错误
您好,请问您使用的是 ATrust 还是零信任客户端?
ATrust,之前一直正常的,今天突然不行了
这个问题可能涉及网络策略变更,我邀请网络安全组的同事一起排查

交互说明

1
坐席点击「+ 邀请」
坐席工作台
2
弹出选人弹窗(组织架构树/搜索)
坐席工作台
3
选择历史消息共享范围
选人弹窗
4
确认邀请 → 后端处理
后端 API
5
企微应用消息通知被邀请人
企微 API
6
被邀请人打开 H5 加入会话
H5 员工端

步骤 2:点击「+ 邀请」→ 弹出选人弹窗

弹窗包含三个区域:组织架构树(左侧)、已选人员(右侧上方)、历史消息共享设置(右侧下方)。

坐席工作台 — 邀请弹窗
选择邀请对象
信息技术部
IT支持组
王工 网络安全
赵磊 系统运维
软件开发组 8人
信息安全部
已选择 (1)
王工
信息技术部·网络安全
历史消息共享
被邀请人加入后能看到哪些历史消息?
邀请说明(可选)

步骤 3:选择人员 — 支持按部门批量邀请

勾选部门节点 = 邀请该部门所有人。每个被邀请人都会收到独立的应用消息通知。

选人 — 勾选整个部门
信息安全部 全部邀请
陈安全 安全主管
刘防护 安全工程师
IT支持组 3人

选人交互规则

操作效果
勾选人员该人员加入已选列表
勾选部门该部门下所有人员加入已选列表
搜索姓名模糊匹配,点击结果直接加入已选
取消勾选从已选列表移除
注意:邀请人数建议上限 10 人。超过 10 人时应提示「当前邀请人数较多,建议优先邀请关键人员」。这不是硬限制,而是用户体验优化。

步骤 4:历史消息共享设置

邀请时坐席可以选择被邀请人能看到哪些历史消息。这是隐私保护的重要设计——避免敏感信息(如员工个人账号问题)被无关人员看到。

三种共享模式对比

模式适用场景隐私风险
共享全部通用IT问题(VPN/网络/打印),无敏感信息
最近10条对话较长,仅需上下文即可理解当前问题
不共享涉及员工个人账号/权限等敏感信息

被邀请人视角 — 共享 vs 不共享

共享全部
[张三] VPN连不上...
[小李] 请问用的是...
[张三] ATrust...
↑ 可看到完整上下文
不共享
[历史消息不可见]
── 加入会话 ──
[王工] 我来看看VPN...
↑ 仅能看到加入后的消息
默认值:建议默认选中「最近10条」,在可见性和隐私之间取得平衡。坐席可根据实际情况调整。

步骤 5:确认邀请 → 后端处理流程

确认邀请 — 后端处理时序
1
坐席点击「确认邀请」
坐席工作台 → POST /api/conversations/:id/invite
2
后端更新 participants 数组,将王工 userid 加入 conversation.participants
后端 → PostgreSQL
3
后端生成邀请卡片消息(含会话ID + H5入口链接 + 邀请说明 + 共享的历史消息摘要)
后端 → 企微应用消息 API
4
企微推送应用消息给王工(单聊卡片消息,非群聊消息)
企微 → 王工企微客户端
5
坐席工作台显示「已邀请王工」系统消息,会话参与者列表更新
WebSocket → 坐席工作台
6
坐席工作台显示「已邀请王工」系统消息,会话参与者列表更新
WebSocket → H5 发起者

API 接口设计

接口方法说明
/api/conversations/:id/invitePOST邀请人员加入会话
/api/conversations/:id/participantsGET获取会话参与者列表
/api/conversations/:id/participants/:uidDELETE移除参与者(坐席/被邀请人退出)
/api/contacts/departmentsGET获取组织架构树(缓存自eHR/企微通讯录)
/api/contacts/searchGET搜索人员(姓名/工号模糊匹配)

步骤 6:被邀请人收到企微应用消息

王工在企微中收到一条应用消息卡片,点击卡片中的按钮即可跳转到 H5 会话页面。

企微消息卡片 — 通知样式
IT
IT智能服务台
刚刚
邀请你加入 IT 支持会话
邀请人:小李(IT支持组)
发起人:张三(IT研发部)
问题摘要:VPN证书错误,ATrust客户端无法连接
邀请说明:需要你协助排查VPN证书问题
加入会话

消息卡片设计要点

  • 使用交互式卡片消息(textcard 类型),而非纯文本
  • 包含问题摘要,让被邀请人判断是否需要立即加入
  • 「加入会话」按钮直接跳转 H5 页面(企微内置浏览器)
  • 如果共享了历史消息,摘要中自动包含最近 2-3 条关键消息

降级方案

如果被邀请人未安装企微处于离线:后端记录邀请状态为「待加入」。被邀请人下次登录企微时会收到消息。同时,坐席工作台显示邀请状态:待加入 / 已加入

步骤 7:被邀请人点击「加入会话」→ H5 页面

王工点击消息卡片按钮 → 企微内置浏览器打开 H5 页面 → 自动加入 WebSocket 会话 → 看到历史消息(如果被共享)→ 可直接发消息

H5 被邀请人视角 — 加入后
IT支持会话
3人参与
── 小李 邀请了 王工 加入会话 ──
VPN 连接不上,提示证书错误
请问您使用的是 ATrust 还是零信任客户端?
ATrust,之前一直正常的,今天突然不行了
── 王工 已加入会话 ──
我来看看,先确认下证书服务状态

加入流程细节

1
点击「加入会话」
企微内置浏览器打开 H5 URL(含 conversation_id + token)
2
H5 自动认证
企微环境 → OAuth2 自动登录;非企微 → Mock 登录
3
建立 WebSocket 连接
加入 conversation 的消息通道
4
拉取历史消息
根据共享设置,显示可查看的历史消息
5
广播「XX 已加入」
所有参与者(坐席+用户+其他被邀请人)都能看到

步骤 8:多人会话持续进行

所有人通过 WebSocket 实时通信。坐席工作台和所有 H5 参与者共享同一个消息通道。坐席拥有管理权限(可移除参与者、结束会话)。

坐席工作台 — 多人会话
张三发起
小李坐席
王工邀请
── 小李 邀请了 王工 加入会话 ──
张三
VPN 连接不上,提示证书错误
小李(坐席)
请问您使用的是 ATrust 还是零信任客户端?
张三
ATrust,今天突然不行了
── 王工 已加入会话 ──
王工(受邀)
证书服务器刚做了更新,我来检查下白名单配置
张三
好的,麻烦了
H5 被邀请人视角 — 王工
IT支持会话
3人 已加入
你可以查看最近10条历史消息
张三
ATrust,今天突然不行了
── 王工 已加入会话 ──
证书服务器刚做了更新,我来检查下白名单配置
张三
好的,麻烦了

坐席管理能力

操作权限说明
邀请人员坐席选择人员加入会话
移除参与者坐席将某人移出会话(不通知)
主动退出被邀请人被邀请人可自行退出
结束会话坐席关闭会话,所有人断开
转让坐席坐席将坐席角色转给其他参与者
与企微群聊的核心区别
1. 会话数据完全在后端控制,不依赖企微群聊 API
2. 被邀请人通过 H5 WebSocket 通信,无需加入企微群
3. 坐席拥有管理权限,可控制参与者和历史可见性
4. 外部联系人(供应商等)也可通过 H5 链接加入