批量查询指定会话

1. 接口定位

• 接口名称: 批量查询指定会话
• 所属域: conversation
• 业务目标: 按会话 ID 列表批量查询指定用户的会话信息

2. 请求定义

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

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
ownerUserID	是	string	会话归属用户 ID
conversationIDs	是	string[]	需要查询的会话 ID 列表

字段约束

• ownerUserID 不能为空。
• conversationIDs 建议传入去重后的会话 ID；不存在的会话不会出现在返回列表中。

4. 响应结构

通用响应包裹

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

data 字段结构

字段	类型	说明
conversations	array	会话列表

conversations 元素（Conversation）

字段	类型	说明
ownerUserID	string	会话归属用户 ID
conversationID	string	会话 ID
conversationType	int32	会话类型（单聊/群聊等）
userID	string	单聊对端用户 ID（单聊时）
groupID	string	群组 ID（群聊时）
recvMsgOpt	int32	接收消息选项
isPinned	bool	是否置顶
isPrivateChat	bool	是否私密会话
groupAtType	int32	群 @ 类型
minSeq	int64	会话最小可见消息序号
maxSeq	int64	会话最大可见消息序号
burnDuration	int32	阅后即焚持续时长
msgDestructTime	int64	消息焚毁时间（毫秒时间戳）
latestMsgDestructTime	int64	最新焚毁消息时间（毫秒时间戳）
isMsgDestruct	bool	是否开启消息焚毁
attachedInfo	string	扩展信息
ex	string	自定义扩展字段

5. 业务规则

• 接口仅返回 ownerUserID 维度下命中的会话。
• 返回列表不保证与 conversationIDs 入参顺序完全一致。
• 未命中的会话 ID 会被忽略，不会单独返回错误项。

6. 错误码与失败场景

错误码	场景	典型报错
1001	参数不合法（如 ownerUserID 为空）	ArgsError
1002	无权限访问	NoPermissionError
500	服务内部错误	ServerInternalError

7. 示例

fetch 请求示例

fetch("http://localhost:10002/conversation/get_conversations", {
  method: "POST",
  headers: {
    operationID: "a2dc9c0d-b0c8-460f-a5a2-844892f2df17",
    token: "<your-token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    ownerUserID: "u_1001",
    conversationIDs: ["si_u_1001_u_1002", "sg_group_001"],
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "ownerUserID": "u_1001",
  "conversationIDs": ["si_u_1001_u_1002", "sg_group_001"]
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "conversations": [
      {
        "ownerUserID": "u_1001",
        "conversationID": "si_u_1001_u_1002",
        "conversationType": 1,
        "userID": "u_1002",
        "recvMsgOpt": 0,
        "isPinned": false,
        "minSeq": 1,
        "maxSeq": 1024
      },
      {
        "ownerUserID": "u_1001",
        "conversationID": "sg_group_001",
        "conversationType": 3,
        "groupID": "group_001",
        "recvMsgOpt": 0,
        "isPinned": true,
        "minSeq": 1,
        "maxSeq": 4096
      }
    ]
  }
}

8. 时序流程

1. 校验请求并解析 ownerUserID 与 conversationIDs。
2. 按指定会话 ID 列表查询会话库。
3. 转换为 Conversation 列表并返回。

9. 变更记录

• 2026-07-06: 新增 get_conversations 文档。