批量获取群资料

1. 接口定位

• 接口名称: 批量获取群资料
• 所属域: group
• 业务目标: 按群组 ID 列表批量返回群基础信息

2. 请求定义

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

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
groupIDs	是	array[string]	群组 ID 列表

字段约束

• groupIDs 不能为空，否则返回参数错误。
• 建议调用方对 groupIDs 做去重，避免重复查询。

4. 响应结构

通用响应包裹

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

data 字段结构

字段	类型	说明
groupInfos	array	群信息列表

groupInfos 元素（GroupInfo）

字段	类型	说明
groupID	string	群组 ID
groupName	string	群名称
notification	string	群公告
introduction	string	群简介
faceURL	string	群头像
createTime	int64	创建时间（毫秒时间戳）
ownerUserID	string	群主用户 ID
memberCount	uint32	群成员数
status	int32	群状态
creatorUserID	string	创建者用户 ID
groupType	int32	群类型
ex	string	扩展字段
needVerification	int32	入群验证开关
lookMemberInfo	int32	是否允许查看成员信息
applyMemberFriend	int32	是否允许成员添加好友

5. 业务规则

• 接口要求有效 token；当前服务端未增加“仅管理员可查”的额外权限拦截。
• 返回结果按服务端命中的群组数据组装；不存在的群组 ID 不会出现在 groupInfos 中。

6. 错误码与失败场景

错误码	场景	典型报错
1001	groupIDs 为空或参数不合法	ArgsError
500	服务内部错误	ServerInternalError

7. 示例

fetch 请求示例

fetch("http://localhost:10002/group/get_groups_info", {
  method: "POST",
  headers: {
    operationID: "a9a95267-1307-4c4f-bd6b-5dff1be7b1fd",
    token: "<your-token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    groupIDs: ["group_001", "group_002"],
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "groupIDs": ["group_001", "group_002"]
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "groupInfos": [
      {
        "groupID": "group_001",
        "groupName": "OpenIM 技术交流群",
        "ownerUserID": "u_admin",
        "memberCount": 86,
        "status": 0
      }
    ]
  }
}

8. 时序流程

1. 校验请求体并检查 groupIDs 是否为空。
2. 按群组 ID 列表读取群资料、群主与成员数。
3. 组装 groupInfos 返回。

9. 变更记录

• 2026-06-20: 首版补充文档发布。