聊天 (Chat)

提供会员与平台客服实时互动的接口与 WebSocket 通道。

鉴权提示：所有的 HTTP 请求与 WebSocket 连接均需要携带 Token。未登录访客使用 BaseToken 并配合前端自行生成的 guest_id 标识，已登录会员使用正式 MemberToken。

1. 建立 WebSocket 连接

客户端必须通过该 WebSocket 通道接收客服的回复和建立长连接心跳。

连接信息

• Endpoint: ws://<domain>/chat/ws
• Params: ?token=<BaseToken_or_MemberToken>&guest_id=<UUID>

通讯数据报文格式

所有通讯数据必须包裹在以下 JSON 结构中：

{
  "type": "类型标识",
  "data": { ... }
}

2.1 心跳检测 (Ping/Pong)

• 客户端发送: {"type": "ping"}
• 服务端返回: {"type": "pong"}
• 说明: 客户端需每隔 30 秒发送一次 ping 以维持连接不断开。

2.2 发送消息 (Client -> Server)

{
  "type": "chat_message",
  "data": {
    "msg_type": "text", 
    "content": "您好，需要帮助"
  }
}

注：如果是发送图片，前端需先调用系统的通用图片上传接口（全局公共的上传 API）获得 URL，再通过 WS 发送 msg_type: "image" 附带 URL。图片在上传前必须经前端 Canvas 压缩（宽带上限 1080px，高度自适应）以确保高清的同时节省存储。

2.3 撤回消息 (Client -> Server)

{
  "type": "recall_message",
  "data": {
    "message_id": "msg_67890"
  }
}

注：只能撤回自己发送的且在 30 分钟内的消息。图片可以撤回。

2.4 修改消息 (Client -> Server)

{
  "type": "edit_message",
  "data": {
    "message_id": "msg_67890",
    "new_content": "修改后的文本内容"
  }
}

注：只能修改自己发送的、文本类型的且在 30 分钟内的消息。图片不能修改。

2.5 接收消息 (Server -> Client)

{
  "type": "new_message",
  "data": {
    "message_id": "msg_67890",
    "sender_type": "agent", // "agent" 或 "system"
    "sender_name": "客服 Alice", // UI 上需展示客服真实姓名
    "msg_type": "text", 
    "content": "好的，请稍等",
    "created_at": "2026-06-14T17:35:00Z"
  }
}

2.6 接收消息更新 (Server -> Client)

当有任何一方（客服或本人）的消息被修改或撤回时，服务端会推送此事件，客户端需根据 message_id 实时更新对应的气泡展示：

{
  "type": "update_message",
  "data": {
    "message_id": "msg_67890",
    "conversation_id": "conv_12345",
    "content": "修改后的内容或保留原样",
    "is_recalled": true, // 是否已撤回 (布尔值)
    "is_edited": true,   // 是否已修改 (布尔值)
    "msg_type": "text"
  }
}

3. 获取历史消息

用于首次打开聊天窗口时，或上拉加载更多时，获取历史聊天记录。此接口**必须采用基于游标（Cursor）**的分页方式。

接口定义

• Endpoint: GET /chat/history
• Auth: 需携带 Token
• Query Params:

  参数名	类型	必填	默认值	描述
  limit	int	否	50	返回条数
  last_message_id	string	否	""	用于游标分页，传入当前列表最旧一条消息的 message_id

响应示例

{
  "code": 0,
  "data": {
    "list": [
      {
        "id": "msg_001",
        "sender_type": "member",
        "msg_type": "text",
        "content": "你好",
        "is_recalled": false,
        "is_edited": false,
        "created_at": "2026-06-14T17:34:00Z"
      }
    ],
    "has_more": true
  },
  "msg": "success"
}

4. 获取未读消息数

用于在非聊天页面（如悬浮窗或通知栏）展示客服回复的未读数。

接口定义

• Endpoint: GET /chat/unread
• Auth: 需携带 Token

响应示例

{
  "code": 0,
  "data": {
    "unread_count": 2
  },
  "msg": "success"
}

5. 标记消息已读

当用户点开聊天窗口并看到新消息时，需调用此接口清空未读提示。

接口定义

• Endpoint: POST /chat/read
• Auth: 需携带 Token

请求参数

{
  "message_id": "msg_001" // 可选。如果不传则将该会话所有未读消息清零
}

6. 图片上传说明

为了保证聊天系统的安全和权限隔离，聊天插件提供了专属的图片上传接口。前端可以直接调用该接口上传经过压缩的图片，获取 URL 后再通过 WebSocket 发送。

接口定义

• Endpoint: POST /chat/upload
• Auth: 需携带 Token (必须为已登录会员的 MemberToken，访客不允许上传图片)
• Content-Type: application/json

请求参数 (JSON)

参数名	类型	必填	描述
file	string	是	图片的 Base64 编码字符串（可以包含 data:image/jpeg;base64, 前缀）
classId	int	否	分类ID，默认为 0
folder	string	否	上传目录，不传默认归档到 chat 目录

发送图片流程

1. 用户在聊天界面选择或拍照。
2. 前端通过 Canvas 进行尺寸压缩（宽度上限 1080px，高度等比缩放），以保证高清且不过分消耗服务器带宽。然后将其导出为 Base64 字符串。
3. 调用专属接口 POST /chat/upload，将 Base64 字符串作为 JSON 的 file 字段上传。
4. 在响应的 data.file.url 中获取到远程 URL 后，通过 WebSocket {"type": "chat_message", "data": {"msg_type": "image", "content": "远程URL"}} 将消息发送给客服。