文档中心
即时通讯
服务端 API
群组相关
查询群成员列表

查询群成员列表

更新时间：2023-12-19 16:05

描述

根据群组 ID 获取群组中的用户列表。

群组 ID 可通过查询 App 下的群列表获取。

接口原型

请求方法：POST
请求地址：https://zim-api.zego.im/?Action=QueryGroupMemberList
传输协议：HTTPS
调用频率限制：20 次/秒

请求参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表请参考调用方式 - 公共请求参数。

参数	类型	是否必选	描述
GroupId	String	是	群组 ID。
Limit	Number	否	单次获取成员的数量，取值范围为 [0, 1000]，即调用本接口一次最多返回 1000 个成员。当群组内成员超过 Limit 时，需调用多次本接口且 Limit 需保持一致。如果传空或大于 1000，则默认取值为 1000。
Next	Number	否	分页拉取标志，第一次填 0，以后填上一次返回的值，返回的 Next 为 0 代表群成员列表获取完毕。例如，群组有 2500 个成员，调用本接口查询群成员列表时：第一次调用本接口，Limit 填 1000，Next 填 0，查询第 1 ～ 1000 名用户；返回结果中的 Next 值为 1 第二次调用本接口，Limit 填 1000，Next 填 1，查询第 1001 ～ 2000 名用户；返回结果中 Next 值为 2。第三次调用本接口，Limit 填 1000，Next 填 2，查询第 2001 ～ 2500 名用户；查询完毕，返回结果中的 Next 为 0。

GroupId 仅支持数字，英文字符和 '!'，'#'，'$'，'%'，'&'，'('，')'，'+'，'-'，':'，';'，'<'，'='，'.'，'>'，'?'，'@'，'['，']'，'^'，'_'，'{'，'}'，'|'，'~'。

请求示例

请求地址 URL：

https://zim-api.zego.im/?Action=QueryGroupMemberList
&<公共请求参数>

请求消息体：

{
   "GroupId":"groupA",
   "Limit":1000,
   "Next":0
}

响应参数

参数	类型	描述
Code	Number	返回码。
Message	String	请求结果的说明信息。
RequestId	String	请求 ID。
TotalCount	Number	服务端开始查询时的群成员总数。
Next	Number	分页拉取的标志。
MemberList	Array of String	群成员信息的集合。
UserId	String	群成员 ID。
UserName	String	群成员名称。
UserNickName	String	用户在群组内的昵称。

响应示例

{
   "Code": 0,
   "Message": "success",
   "RequestId": "343649807833778782",
   "TotalCount": 1680,
   "Next": 168,
   "MemberList": [
      {
         "UserId": "u1",
         "UserName": "userName1",
         "UserNickName": "userNickName1"
      },
      {
         "UserId": "u2",
         "UserName": "userName2",
         "UserNickName": "userNickName2"
      }
   ]
}

返回码

以下仅列出了接口业务逻辑相关的返回码，完整返回码请参考全局返回码。

返回码	说明	处理建议
660000002	参数错误。	请参考请求参数输入正确参数。
660600001	群不存在。	请确认 GroupId 是否正确。
660600003	查询群成员列表出错。	请联系 ZEGO 技术支持。
660600004	调用 QueryGroupMemberList 接口的频率超出限制。	调用频率为 20 次/秒，请勿超出限制。