搜索消息

1. 接口定位

• 接口名称: 搜索消息
• 所属域: msg
• 业务目标: 按会话对象、发送人、时间与消息类型检索消息记录

2. 请求定义

• Method: POST
• Path: /msg/search_msg
• Content-Type: 推荐 application/json
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 必填，需要通过 Header token 传入有效令牌
• 幂等性: 幂等（只读操作）

3. 请求参数

Header 参数

字段	必填	类型	说明
operationID	是	string	链路追踪 ID
token	是	string	登录令牌

Body 参数

字段	必填	类型	说明
sendID	否	string	发送者用户 ID
recvID	否	string	接收方 ID（单聊对端 userID 或群聊 groupID）
contentType	否	int32	消息内容类型
sessionType	否	int32	会话类型（单聊/群聊等）
sendTime	否	string	发送日期，格式 YYYY-MM-DD
pagination	否	object	分页参数

pagination 字段

字段	必填	类型	说明
pageNumber	否	int32	页码（从 1 开始）
showNumber	否	int32	每页条数

字段约束

• sendTime 必须是 YYYY-MM-DD，否则返回参数错误。
• 不传过滤字段时，按分页返回全量检索结果。

4. 响应结构

通用响应包裹

字段	类型	说明
errCode	int	错误码，0 表示成功
errMsg	string	错误简述
errDlt	string	错误详情
data	any	业务数据

data 字段结构

字段	类型	说明
chatLogs	array	搜索结果列表
chatLogsNum	int32	命中总数

chatLogs 元素（SearchChatLog）

字段	类型	说明
isRevoked	bool	是否已撤回
chatLog	object	消息详情

chatLog 关键字段

字段	类型	说明
serverMsgID	string	服务端消息 ID
clientMsgID	string	客户端消息 ID
sendID	string	发送者 ID
recvID	string	接收者 ID
groupID	string	群组 ID（群聊时）
senderNickname	string	发送者昵称
recvNickname	string	接收者昵称
contentType	int32	消息类型
content	string	消息内容（字符串化）
seq	int64	消息序号
sendTime	int64	发送时间（毫秒时间戳）
createTime	int64	创建时间（毫秒时间戳）

5. 业务规则

• 群聊结果会附带群名、群主、成员数等聚合信息。
• 单聊结果会补齐接收方昵称等展示字段。

6. 错误码与失败场景

错误码	场景	典型报错
1001	sendTime 格式非法	invalid sendTime
1002	无权限访问	NoPermissionError
500	服务内部错误	ServerInternalError

7. 示例

fetch 请求示例

fetch("http://localhost:10002/msg/search_msg", {
  method: "POST",
  headers: {
    operationID: "f4f4ddf6-728f-4a8f-bd9e-f87c67e33ca5",
    token: "<your-token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    recvID: "group_001",
    sessionType: 3,
    sendTime: "2026-04-09",
    pagination: {
      pageNumber: 1,
      showNumber: 20
    }
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "recvID": "group_001",
  "sessionType": 3,
  "sendTime": "2026-04-09",
  "pagination": {
    "pageNumber": 1,
    "showNumber": 20
  }
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "chatLogsNum": 1,
    "chatLogs": [
      {
        "isRevoked": false,
        "chatLog": {
          "serverMsgID": "c88f...",
          "clientMsgID": "f95a...",
          "sendID": "u_1001",
          "recvID": "group_001",
          "contentType": 101,
          "content": "{\"text\":\"hello\"}",
          "seq": 1024,
          "sendTime": 1710000000000
        }
      }
    ]
  }
}

8. 时序流程

1. 解析过滤条件并执行消息库检索。
2. 补齐用户/群展示信息。
3. 组装检索结果返回。

9. 变更记录

• 2026-04-09: 首版补充文档发布。