OpenIM Chat Docs

Appearance

获取群成员列表（chatx） ​

1. 接口定位 ​

  • 接口名称: 获取群成员列表（chatx）
  • 所属域: chat/group（chatx）
  • 业务目标: 按群 ID 拉取群成员分页列表，并提供稳定可用的关键字检索能力

2. 请求定义 ​

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

3. 请求参数 ​

Header 参数 ​

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

Body 参数 ​

字段必填类型说明
groupID是string群组 ID
keyword否string关键字（支持匹配群昵称 nickname 与成员 ID userID）
filter否int32兼容保留字段；当前不参与过滤
pagination否RequestPagination分页参数

字段约束 ​

  • groupID 必填，不能为空。
  • pagination 为空时，默认 pageNumber=1、showNumber=20。
  • pagination.pageNumber <= 0 时按 1 处理；pagination.showNumber <= 0 时按 20 处理。
  • keyword 为空时走稳定分页查询；keyword 非空时进入关键字检索逻辑。

4. 响应结构 ​

通用响应包裹 ​

字段类型说明
errCodeint错误码，0 表示成功
errMsgstring错误简述
errDltstring错误详情
dataobject业务数据

data 字段结构 ​

字段类型说明
totaluint32匹配成员总数
membersarray<GroupMemberFullInfo>成员列表

members 元素（GroupMemberFullInfo） ​

常用字段包括：

  • groupID
  • userID
  • nickname
  • roleLevel
  • joinTime
  • faceURL
  • muteEndTime
  • inviterUserID
  • ex

5. 权限与业务规则 ​

  • 管理员可查询任意群成员。
  • 普通用户必须是目标群成员，才允许查询。
  • keyword 为空时：透传稳定分页链路。
  • keyword 非空时：
    1. 先按空 keyword 拉取群成员分页数据（分批扫描）；
    2. 在服务端本地按 nickname 与 userID 做不区分大小写包含匹配；
    3. 对匹配结果执行分页并返回。
  • filter 当前不影响结果，保留仅为兼容历史请求结构。

6. 与 OpenIM 同名接口差异说明 ​

  • OpenIM 官方镜像中的 /group/get_group_member_list 在 keyword 分支存在已知问题，常见表现为返回空列表。
  • 本接口通过 chatx 侧兜底过滤规避该问题，保证 keyword 检索可用。
  • 本接口额外支持通过 userID 命中关键字（OpenIM 原实现主要按 nickname）。

7. 错误码与失败场景 ​

错误码场景典型报错
1001参数错误groupID is empty
1002token 无效/缺失NoPermission
1002普通用户非群成员NoPermission（op user not in group）
5000+上游 OpenIM 调用失败透传上游错误码与错误信息

8. 示例 ​

请求示例（普通分页） ​

json
{
  "groupID": "group_001",
  "pagination": {
    "pageNumber": 1,
    "showNumber": 20
  }
}

请求示例（关键字检索） ​

json
{
  "groupID": "group_001",
  "keyword": "u_1001",
  "pagination": {
    "pageNumber": 1,
    "showNumber": 10
  }
}

成功响应示例 ​

json
{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "total": 1,
    "members": [
      {
        "groupID": "group_001",
        "userID": "u_1001",
        "nickname": "alice",
        "roleLevel": 2,
        "joinTime": 1710000000000,
        "muteEndTime": 0
      }
    ]
  }
}

9. 时序流程 ​

  1. 中间件校验 token。
  2. RPC 层校验调用者身份（管理员或普通用户）。
  3. 若为普通用户，先校验其是否在目标群内。
  4. 按 keyword 走分页透传分支或本地过滤分支。
  5. 返回分页后的群成员列表。

10. 变更记录 ​

  • 2026-07-28: 首版发布，新增 chatx 群成员列表关键字兜底能力文档。