获取群成员列表

获取指定群组的成员信息，包括成员名字与 ID。

前提条件

• 调用该接口的应用，需要开启机器人能力。
• 当前接口的操作者（机器人或用户）必须在被查询的群组内。

使用限制

• 该接口不会返回群组内的机器人成员。
• 由于返回的群成员列表会过滤掉机器人成员，因此返回的群成员个数可能会小于指定的 page_size。
• 如果有同一时间加入群的群成员，会一次性返回，这会导致返回的群成员个数可能会大于指定的 page_size。
• 获取内部群信息时，操作者须与群组在同一租户下。

请求

项目	值
HTTP URL	https://open.feishu.cn/open-apis/im/v1/chats/:chat_id/members
HTTP Method	GET
接口频率限制	1000 次/分钟、50 次/秒
支持的应用类型	custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可	im:chat 获取与更新群组信息 im:chat:readonly 获取群组信息 im:chat.members:read 查看群成员 im:chat.group_info:readonly 读取群信息（历史版本）
字段权限要求	> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 contact:user.employee_id:readonly 获取用户 user ID

请求头

名称	类型	必填	描述
Authorization	string	是	tenant_access_token 或 user_access_token 值格式："Bearer access_token" 示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token

路径参数

名称	类型	描述
chat_id	string	群 ID。获取方式： - 创建群，从返回结果中获取该群的 chat_id。 - 调用获取用户或机器人所在的群列表接口，可以查询用户或机器人所在群的 chat_id。 - 调用搜索对用户或机器人可见的群列表，可搜索用户或机器人所在的群、对用户或机器人公开的群的 chat_id。 示例值："oc_a0553eda9014c201e6969b478895c230"

查询参数

名称	类型	必填	描述
member_id_type	string	否	用户 ID 类型 示例值：open_id 可选值有： - open_id: 标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。了解更多：如何获取 Open ID？ - union_id: 标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。了解更多：如何获取 Union ID？ - user_id: 标识一个用户在某个租户内的身份。同一个用户在租户 A 和租户 B 内的 User ID 是不同的。在同一个租户内，一个用户的 User ID 在所有应用（包括商店应用）中都保持一致。User ID 主要用于在不同的应用间打通用户数据。了解更多：如何获取 User ID？ 默认值：open_id 当值为 user_id，字段权限要求： contact:user.employee_id:readonly 获取用户 user ID
page_size	int	否	分页大小，用来限制一次请求所返回的数据条目数。 - 由于返回的群成员列表会过滤掉机器人成员，因此返回的群成员个数可能会小于指定的 page_size。 - 如果有同一时间加入群的群成员，会一次性返回，这会导致返回的群成员个数可能会大于指定的 page_size。 示例值：20 默认值：20 数据校验规则： - 最大值：100
page_token	string	否	分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果 示例值：WWxHTStrOEs5WHZpNktGbU94bUcvMWlxdDUzTWt1OXNrRmlLaGRNVG0yaz0=

响应

响应体

名称	类型	描述
code	int	错误码，非 0 表示失败
msg	string	错误描述
data	\-	-
└ items	list_member\[\]	成员列表
└ member_id_type	string	成员的用户 ID 类型，与查询参数中的 member_id_type 相同。取值为：open_id、user_id、union_id其中之一。
└ member_id	string	成员的用户ID，ID 值与查询参数中的 member_id_type 对应。 不同 ID 的说明参见 用户相关的 ID 概念
└ name	string	名字
└ tenant_key	string	租户Key，为租户在飞书上的唯一标识，用来换取对应的tenant_access_token，也可以用作租户在应用中的唯一标识
└ page_token	string	分页标记，当 has_more 为 true 时，会同时返回新的 page_token，否则不返回 page_token
└ has_more	boolean	是否还有更多项
└ member_total	int	成员总数

响应体示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "items": [
            {
                "member_id_type": "open_id",
                "member_id": "ou_9204a37300b3700d61effaa439f34295",
                "name": "张三",
                "tenant_key": "736588c9260f175d"
            }
        ],
        "page_token": "dmJCRHhpd3JRbGV1VEVNRFFyTitRWDY5ZFkybmYrMEUwMUFYT0VMMWdENEtuYUhsNUxGMDIwemtvdE5ORjBNQQ==",
        "has_more": true,
        "member_total": 2
    }
}

错误码

HTTP状态码	错误码	描述	排查建议
400	232001	Your request contains an invalid request parameter.	参数错误，参考接口文档提供的参数描述，检查输入参数是否有误。
400	232004	Such an app does NOT exist.	作为操作者的 app_id 不存在，请联系技术支持。
400	232006	Your request specifies a chat_id which is invalid.	无效的 chat_id，请检查 chat_id 是否正确。获取方式： - 创建群，从返回结果中获取该群的 chat_id。 - 调用获取用户或机器人所在的群列表接口，可以查询用户或机器人所在群的 chat_id。 - 调用搜索对用户或机器人可见的群列表，可搜索用户或机器人所在的群、对用户或机器人公开的群的 chat_id。
400	232009	Your request specifies a chat which has already been dissolved.	群组已被解散，无法操作。
400	232010	Operator and chat can NOT be in different tenants.	调用接口的操作者和被操作的群组不在同一租户下，无法操作。需确保当前的操作者和被操作的群组在同一租户下。
400	232011	Operator can NOT be out of the chat.	操作者不在群组中。你需要将当前调用 API 的应用或用户加入待操作的群组后重试。
400	232025	Bot ability is not activated.	应用未启用机器人能力。你需要登录开发者后台，在应用详情页的 应用能力 > 添加应用能力 页面内，添加 机器人 能力，并发布应用使配置生效。具体操作参见机器人能力。
400	232033	The operator or invited bots does NOT have the authority to manage external chats without the scope.	没有权限操作外部群，且暂不支持申请该权限。
400	232034	The app is unavailable or inactivated by the tenant.	应用在本租户下未安装或未启用。需要先安装应用，再使用应用调用接口。

更多错误码信息，参见通用错误码。