IM 系统坐席及临时客户工作流程
-
系统概述
本 IM 系统通过 WebSocket 和 RESTful API 提供实时聊天功能，支持 坐席（Agent） 和 临时客户（Temporary Customer） 之间的沟通。系统主要用于客服场景，涉及会话管理、消息发送、消息已读标记、未读消息查询等功能。
1.1 角色定义
- 组织头（Admin）:
- 直接注册就是组织头
- 管理坐席账户（创建、修改、删除）。
- 配置组织信息（名称、代码、简介、头像）。
- 无直接聊天功能，主要负责管理。
- 坐席（Agent）:
- 由组织头创建，隶属于特定组织。
- 与临时客户进行实时聊天，处理客户咨询。
- 可查询会话历史、标记消息已读、转接会话。
- 临时客户（Temporary Customer）:
- 无需注册，匿名用户，通过创建临时会话与坐席沟通。
- 可发送消息、接收消息、标记消息已读。
1.2 技术架构
- WebSocket: 用于实时消息传递、心跳检测和会话通知。
- RESTful API: 用于会话管理、聊天记录查询、坐席管理、用户设置等。
- 认证机制:
- 坐席：通过 JWT token 认证（登录后获取）。
- 临时客户：通过临时 token（创建会话时生成）。
- 数据存储:
- 会话和消息数据存储在数据库。
- Redis 用于 token 验证和会话状态管理。
- 功能模块
2.1 坐席管理（组织头）
- 创建坐席: 组织头通过 /api/im/front/agents POST 接口创建坐席，设置用户名、昵称、密码。
- 修改坐席: 通过 /api/im/front/agents/modifyAgent PUT 接口更新坐席信息（用户名、昵称、密码）。
- 删除坐席: 通过 /api/im/front/agents/deleteAgent/{agentId} DELETE 接口逻辑删除坐席（禁用账户）。
- 查询坐席: 通过 /api/im/front/agents/getSubAgents GET 接口获取下属坐席列表，用于会话转接等场景。
2.2 会话管理
- 创建临时会话: 临时客户通过 /api/im/front/sessions/createSession POST 接口创建会话，生成临时用户 ID 和 token。
- 查询活跃会话: 坐席通过 /api/im/front/sessions/list GET 接口获取活跃会话列表-左侧会话列表使用。
- 查询会话历史: 坐席通过 /api/im/front/sessions/page GET 接口分页查询会话历史（支持状态过滤）。
- 转接会话: 坐席通过 /api/im/front/sessions/transfer POST 接口将会话转接给其他坐席。
2.3 聊天功能
- 发送消息: 通过 WebSocket UP_SEND_MESSAGE 消息类型发送聊天消息。
- 标记已读: 通过 WebSocket UP_MARK_READ 或 REST /api/im/front/chats/markRead POST 接口标记消息为已读。
- 查询未读消息数: 通过 WebSocket UP_QUERY_UNREAD 查询所有会话的未读消息数。
- 查询聊天记录: 坐席通过 /api/im/front/chats/pageList4Chat 或 /api/im/front/chats/pageList4Session GET 接口分页查询历史聊天记录。
2.4 用户设置（组织头）
- 更新头像: 通过 /api/im/front/user POST 接口上传头像，同步更新下属坐席。
- 修改昵称: 通过 /api/im/front/user/modifyNickName PUT 接口更新个人昵称。
- 修改组织信息: 通过 /api/im/front/user/modifyOrgName, /api/im/front/user/modifyOrgCode, /api/im/front/user/modifyOrgBrief PUT 接口更新组织名称、代码、简介，同步更新下属坐席。
- 工作流程
3.1 坐席工作流程
- 登录:
- 坐席通过登录接口（未提供具体代码，假设存在）获取 JWT token。
- 使用 token 建立 WebSocket 连接（ws://
:8081/ws）。 - 初始化会话:
- WebSocket 连接成功后，服务器通过 ImSessionManager 加载坐席的活跃会话（status=1）。
- 客户端调用 /api/im/front/sessions/listActiveSessions 获取活跃会话列表，显示未读消息数。
- 处理消息:
- 接收消息: 临时客户发送消息后，服务器通过 WebSocket 推送 DOWN_NEW_MESSAGE 通知坐席。
- 发送消息: 坐席通过 WebSocket UP_SEND_MESSAGE 发送消息，收到 DOWN_MESSAGE_SENT 确认。
- 标记已读: 坐席通过 WebSocket UP_MARK_READ 或 REST /api/im/front/chats/markRead 标记消息为已读，服务器推送 DOWN_MARK_READ 通知会话参与者。
- 查询未读消息:
- 坐席通过 WebSocket UP_QUERY_UNREAD 查询所有会话的未读消息数，收到 DOWN_QUERY_UNREAD 响应。
- 查询聊天记录:
- 在对话窗口中，调用 /api/im/front/chats/pageList4Chat 获取指定会话的聊天记录（自动标记已读）。
- 在其他场景，调用 /api/im/front/chats/pageList4Session 查询历史记录。
- 转接会话:
- 坐席调用 /api/im/front/sessions/transfer 将会话转接给其他坐席。
- 新坐席收到 DOWN_NEW_SESSION 通知，旧坐席被移除会话。
- 保持连接:
- 每 30 秒发送 WebSocket UP_HEARTBEAT，接收 DOWN_HEARTBEAT 响应。
- 如果 60 秒内无消息，服务器关闭连接。
3.2 临时客户工作流程
- 创建会话:
- 临时客户调用 /api/im/front/sessions/createSession 创建会话，获取临时用户 ID 和 token。
- 建立连接:
- 使用返回的 token 建立 WebSocket 连接（ws://
:8081/ws?token= ）。 - 发送消息:
- 通过 WebSocket UP_SEND_MESSAGE 发送消息，收到 DOWN_MESSAGE_SENT 确认。
- 接收坐席消息通过 DOWN_NEW_MESSAGE 推送。
- 标记已读:
- 通过 WebSocket UP_MARK_READ 标记消息为已读，服务器推送 DOWN_MARK_READ。
- 查询未读消息:
- 通过 WebSocket UP_QUERY_UNREAD 查询未读消息数，收到 DOWN_QUERY_UNREAD。
- 保持连接:
- 每 30 秒发送 UP_HEARTBEAT，接收 DOWN_HEARTBEAT。
- 如果 60 秒内无消息，服务器关闭连接。
3.3 组织头工作流程
- 登录:
- 组织头通过登录接口获取 JWT token。
- 管理坐席:
- 创建: 调用 /api/im/front/agents POST 创建坐席。
- 修改: 调用 /api/im/front/agents/modifyAgent PUT 更新坐席信息。
- 删除: 调用 /api/im/front/agents/deleteAgent/{agentId} DELETE 禁用坐席。
- 查询: 调用 /api/im/front/agents/getSubAgents GET 获取坐席列表。
- 管理组织信息:
- 更新头像：调用 /api/im/front/user POST 上传头像。
- 修改昵称：调用 /api/im/front/user/modifyNickName PUT。
- 修改组织信息：调用 /api/im/front/user/modifyOrgName, /api/im/front/user/modifyOrgCode, /api/im/front/user/modifyOrgBrief PUT。
- 所有组织信息变更自动同步到下属坐席。
- 交互示例
4.1 坐席处理客户消息
- 建立 WebSocket 连接:
javascript
javascript
const ws = new WebSocket('ws://<server>:8081/ws', ['<jwt-token>']);
ws.onopen = () => {
setInterval(() => {
ws.send(JSON.stringify({
type: 'UP_HEARTBEAT',
data: { timestamp: Date.now() }
}));
}, 30000);
};
- 查询活跃会话:
bash
bash
curl -H "Authorization: Bearer <jwt-token>" \
http://<server>/api/im/front/sessions/listActiveSessions
响应：
json
json
[
{
"id": 123,
"userId": 1001,
"tempUserId": 2001,
"status": 1,
"lastMessageTime": 1697059200000,
"unreadCount": 2
}
]
- 发送消息:
json
json
{
"type": "UP_SEND_MESSAGE",
"data": {
"sessionId": 123,
"content": "How can I assist you today?"
}
}
接收：
json
json
{
"type": "DOWN_MESSAGE_SENT",
"data": {
"chatId": 456,
"sessionId": 123,
"sendTime": 1697059201000
}
}
- 接收客户消息:
json
json
{
"type": "DOWN_NEW_MESSAGE",
"data": {
"chat": {
"id": 457,
"sessionId": 123,
"senderId": 2001,
"receiverId": 1001,
"content": "I have a question about my account.",
"sendTime": 1697059202000,
"isRead": false,
"chatType": 2
},
"sessionId": 123,
"unreadCount": 3
}
}
- 标记已读:
json
json
{
"type": "UP_MARK_READ",
"data": {
"sessionId": 123
}
}
4.2 临时客户发起咨询
- 创建会话:
bash
bash
curl -X POST http://<server>/api/im/front/sessions/createSession \
-H "Content-Type: application/json" \
-d '{"orgCode":"ORG123"}'
响应：
json
json
{
"sessionId": 123,
"tempUserId": 2001,
"token": "<temporary-token>"
}
- 建立 WebSocket 连接:
javascript
javascript
const ws = new WebSocket('?token=<temporary-token>');
- 发送消息:
json
json
{
"type": "UP_SEND_MESSAGE",
"data": {
"sessionId": 123,
"content": "I need help with my account."
}
}
4.3 组织头管理坐席
- 创建坐席:
bash
bash
curl -X POST http://<server>/api/im/front/agents \
-H "Authorization: Bearer <jwt-token>" \
-H "Content-Type: application/json" \
-d '{"username":"agent1","nickName":"Agent One","password":"pass123"}'
- 修改组织名称:
bash
bash
curl -X PUT http://<server>/api/im/front/user/modifyOrgName \
-H "Authorization: Bearer <jwt-token>" \
-H "Content-Type: application/json" \
-d '"New Org Name"'
-
注意事项
-
认证:
- 坐席和组织头需使用有效的 JWT token。
- 临时客户使用创建会话时生成的临时 token。
- 会话状态:
- 仅活跃会话（status=1）支持消息交互。
- 非活跃会话可通过历史查询查看。
- 消息已读:
- 标记已读会通知所有会话参与者。
- 查询聊天记录时自动标记已读（/api/im/front/chats/pageList4Chat）。
- 转接会话:
- 转接后原坐席被移除，新坐席收到通知。
- 确保目标坐席在线且有权限。
- 心跳:
- 客户端需每 30 秒发送 UP_HEARTBEAT，否则 60 秒后连接断开。