群成员

本页的接口用来管理群成员：查询成员列表、添加和移出成员、修改成员的群昵称和成员属性、设置管理员、禁言成员。群的基本概念（成员角色、加入方式、版本号）见群组管理。

服务端添加成员时，用户直接加入群，不需要本人确认，也不看用户的入群设置和群的邀请设置；如果希望用户自己决定是否加入，请让成员在客户端邀请他，见入群申请与邀请。

成员发生变化（加入、离开，角色、群昵称、禁言变化）时，群的在线成员会实时收到通知；成员加入和离开时，群会话中会出现相应的提示消息。每次变化都让群的 member_version 加一，一次批量操作只加一。

查询群成员列表

分页返回群的成员，每项带用户的昵称和头像，不必再逐个查询用户资料。可以只列出某种角色的成员，或只列出被禁言的成员（禁言名单）。

成员按固定的顺序返回（与加入时间无关）。账号刚被删除、尚未被系统移出群的成员不在列表中，所以一页的条数可能少于 limit，是否还有下一页以 next_cursor 为准。已解散的群在成员被移出之前（解散后约 1 小时内）也可以查询。

GET/{org_name}/{app_name}/groups/{group_id}/members

路径参数

org_name、app_name 见接入概述。

参数	类型	说明
`group_id`	String	群 ID

查询参数

参数	类型	必填	说明
`role`	String	否	只列出这种角色的成员：`owner`、`admin` 或 `member`
`muted`	Boolean	否	为 `true` 时只列出当前被禁言的成员；默认 `false`
`known_version`	Number	否	你保存的成员列表版本号。请求第一页（不带 `cursor`）时，与当前的 `member_version` 相同则只返回版本号和 `"not_modified": true`，不返回列表
`limit`	Number	否	每页条数，默认 100，取值 1 到 500
`cursor`	String	否	下一页的游标，见分页

请求示例

bash

curl -X GET "$IM_API/$ORG/$APP/groups/99582624883802112/members?limit=2" \
  -H "Authorization: Bearer $APP_TOKEN"

响应

成功返回 200 OK：

字段	类型	说明
`member_version`	Number	当前的成员列表版本号
`not_modified`	Boolean	为 `true` 时表示成员列表与 `known_version` 相同，响应中只有 `member_version` 和这个字段
`member_count`	Number	群的成员总数（含群主），不受筛选条件影响
`items`	Array<Object>	本页的成员，每项为群成员对象
`next_cursor`	String	下一页的游标，没有下一页时为 `null`

json

{
  "member_version": 18,
  "not_modified": false,
  "member_count": 3,
  "items": [
    {
      "username": "zhangsan",
      "nickname": "张三",
      "avatar_url": "https://cdn.example.com/avatar/zhangsan.png",
      "role": "owner",
      "group_nickname": "",
      "attributes": null,
      "muted": false,
      "muted_until": null,
      "joined_via": "create",
      "inviter": null,
      "joined_at": "2026-10-02T19:05:47.929Z"
    },
    {
      "username": "lisi",
      "nickname": "李四",
      "avatar_url": "https://cdn.example.com/avatar/lisi.png",
      "role": "member",
      "group_nickname": "李四爸爸",
      "attributes": {
        "relation": "父亲",
        "student_no": "20230512"
      },
      "muted": false,
      "muted_until": null,
      "joined_via": "create",
      "inviter": null,
      "joined_at": "2026-10-02T19:05:47.929Z"
    }
  ],
  "next_cursor": "9H7GjqY3MBC44LVD3-8KK34h7wBQEruWHZtZcFgxf11xvlhOrIFavUbSflQL6KuoIRlUZ_8q3QsEV7gmWm-j_WxPu_kFPboldMeSWhLbkx0BKBBE"
}

带 known_version 且成员列表没有变化时：

json

{
  "member_version": 18,
  "not_modified": true
}

错误

HTTP 状态码	`code`	说明
400	`invalid_argument`	`role`、`muted`、`known_version` 的取值不合法，或 `limit` 超出范围
404	`not_found`	群不存在

批量添加群成员

把一批用户直接加入群，一次最多 100 个。服务端添加不需要被添加的人确认，不看用户的入群设置、群的邀请设置和用户之间的黑名单，也不调用加群前回调，但仍然检查：

用户不在群黑名单中；
群人数没有超过上限（群组对象的 max_members）；
用户加入的群数没有超过上限（应用运行策略中的 max_groups_per_user，默认 500，且不超过应用套餐的额度）。

每个用户分别处理，某个失败不影响其他用户，响应中逐个列出结果，规则见批量接口。已经是成员的视为成功，不重复加入。加入的成员 joined_via 为 server；他们在本群尚未处理的入群申请和邀请自动失效。

这个接口按用户名个数计入应用的调用额度，见限流与应用状态。

POST/{org_name}/{app_name}/groups/{group_id}/members/batch

路径参数

org_name、app_name 见接入概述。

参数	类型	说明
`group_id`	String	群 ID

请求体

字段	类型	必填	说明
`usernames`	Array<String>	是	要添加的用户名，1 到 100 个（不区分大小写，重复的只处理一次）

请求示例

bash

curl -X POST "$IM_API/$ORG/$APP/groups/99582624883802112/members/batch" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "usernames": ["zhaoliu", "zhouba", "lisi", "sunqi", "nobody"]
  }'

响应

成功返回 200 OK：

字段	类型	说明
`changed`	Boolean	是否有人加入了群
`member_version`	Number	成员列表的版本号：有人加入时为加入后的新版本号，否则为当前的版本号
`results`	Array<Object>	每个用户的结果，按请求中的顺序排列，见批量操作结果。成功的 `status` 为 `joined`（已加入）或 `already_member`（原本就是成员）

json

{
  "changed": true,
  "member_version": 24,
  "results": [
    { "username": "zhaoliu", "status": "joined" },
    { "username": "zhouba", "status": "joined" },
    { "username": "lisi", "status": "already_member" },
    {
      "username": "sunqi",
      "code": "permission_denied",
      "message": "该用户在群黑名单中",
      "details": { "reason": "group_blacklisted" }
    },
    { "username": "nobody", "code": "not_found", "message": "用户不存在" }
  ]
}

错误

HTTP 状态码	`code`	说明
400	`invalid_argument`	`usernames` 为空或超过 100 个
403	`group_disabled`	群已被封禁，不能加人；`details.disabled_by` 为封禁方
403	`app_unavailable`	应用处于只读状态，不能加人
404	`not_found`	群不存在或已解散

批量移出群成员

把一批成员移出群，一次最多 100 个。不能移出群主，要先转让群主。已经不是成员的视为移出成功。被移出的人之后可以再被添加或邀请，除非同时把他拉入了群黑名单（拉黑时会自动移出群，不必先调用这个接口）。

被移出的人和群的在线成员会实时收到通知，群会话中出现成员被移出的提示消息；被移出的人还会收到“你已被移出群聊”的离线推送（App 不在前台时），他对这个群设置的会话免打扰随之删除。被移出的人不能再在客户端查看和下载群文件，他上传的群文件仍留在群中。被封禁的群也可以移出成员。这个接口按用户名个数计入应用的调用额度。

POST/{org_name}/{app_name}/groups/{group_id}/members/batch-delete

路径参数

org_name、app_name 见接入概述。

参数	类型	说明
`group_id`	String	群 ID

请求体

字段	类型	必填	说明
`usernames`	Array<String>	是	要移出的用户名，1 到 100 个（不区分大小写，重复的只处理一次）

请求示例

bash

curl -X POST "$IM_API/$ORG/$APP/groups/99582624883802112/members/batch-delete" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "usernames": ["zhouba", "zhangsan", "wujiu"]
  }'

响应

成功返回 200 OK，字段同批量添加群成员，其中 changed 表示是否有人被移出。成功的 status 为 removed（已移出）或 not_member（原本就不是成员）。

json

{
  "changed": true,
  "member_version": 25,
  "results": [
    { "username": "zhouba", "status": "removed" },
    { "username": "zhangsan", "code": "permission_denied", "message": "不能移出群主" },
    { "username": "wujiu", "status": "not_member" }
  ]
}

错误

HTTP 状态码	`code`	说明
400	`invalid_argument`	`usernames` 为空或超过 100 个
404	`not_found`	群不存在或已解散

查询群成员

查询一个用户在群里的信息。

GET/{org_name}/{app_name}/groups/{group_id}/members/{username}

路径参数

org_name、app_name 见接入概述。

参数	类型	说明
`group_id`	String	群 ID
`username`	String	用户名

请求示例

bash

curl -X GET "$IM_API/$ORG/$APP/groups/99582624883802112/members/wangwu" \
  -H "Authorization: Bearer $APP_TOKEN"

响应

成功返回 200 OK，响应体为群成员对象。

json

{
  "username": "wangwu",
  "nickname": "王五",
  "avatar_url": "https://cdn.example.com/avatar/wangwu.png",
  "role": "admin",
  "group_nickname": "",
  "attributes": null,
  "muted": false,
  "muted_until": null,
  "joined_via": "create",
  "inviter": null,
  "joined_at": "2026-10-02T19:05:47.929Z"
}

错误

HTTP 状态码	`code`	说明
403	`not_group_member`	这个用户不是群成员
404	`not_found`	群不存在，或用户不存在

修改群成员资料

修改成员在本群的群昵称和成员属性。只修改请求中出现的字段。群昵称和成员属性对群内全部成员可见，用户自己也可以在客户端修改。被封禁的群也可以修改，便于清除违规的群昵称。

修改的群昵称要经过内容安全检查（你的服务端提交的默认只按平台规则检查，见服务端提交的内容），与原值相同或清空时不检查：不通过时不做任何修改，返回 403 content_rejected；命中替换规则的，写入替换后的群昵称。成员属性不检查。

PATCH/{org_name}/{app_name}/groups/{group_id}/members/{username}

路径参数

org_name、app_name 见接入概述。

参数	类型	说明
`group_id`	String	群 ID
`username`	String	成员的用户名

请求体

至少包含一个字段。

字段	类型	必填	说明
`group_nickname`	String	否	群昵称，最长 64 个字符，不能包含换行等控制字符，首尾的空白会被去掉；传空字符串表示清除
`attributes`	Object	否	成员属性，字符串键值对，如学号、职务。按项合并：出现的键被新增或覆盖，值为 `null` 的键被删除，没有出现的键保持不变；整个字段为 `null` 时清空全部成员属性。合并后最多 16 项，JSON 编码后合计不超过 1 KB；键为 1 到 32 个字符，只能包含字母、数字和 `_`、`-`、`.`

请求示例

bash

curl -X PATCH "$IM_API/$ORG/$APP/groups/99582624883802112/members/lisi" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "group_nickname": "李四爸爸",
    "attributes": { "student_no": "20230512", "relation": "父亲" }
  }'

响应

成功返回 200 OK：

字段	类型	说明
`member`	Object	修改后的群成员对象
`changed`	Boolean	这次请求是否改变了成员。与原值相同时为 `false`，`member_version` 不变，也不会通知成员
`member_version`	Number	成员列表的版本号：有变化时为变化后的新版本号，否则为当前的版本号

json

{
  "member": {
    "username": "lisi",
    "nickname": "李四",
    "avatar_url": "https://cdn.example.com/avatar/lisi.png",
    "role": "member",
    "group_nickname": "李四爸爸",
    "attributes": {
      "relation": "父亲",
      "student_no": "20230512"
    },
    "muted": false,
    "muted_until": null,
    "joined_via": "create",
    "inviter": null,
    "joined_at": "2026-10-02T19:05:47.929Z"
  },
  "changed": true,
  "member_version": 23
}

错误

HTTP 状态码	`code`	说明
400	`invalid_argument`	没有要修改的字段，或字段不合法（如群昵称过长、成员属性超过上限）；请求中包含其他字段（如 `role`，设置角色请用设置群成员角色）
403	`not_group_member`	这个用户不是群成员
403	`app_unavailable`	应用处于只读状态，不能修改
403	`content_rejected`	群昵称未通过内容安全检查，`details.field` 为 `group_nickname`，`details.reason` 说明原因，见调用方看到的错误
404	`not_found`	群不存在或已解散，或用户不存在

设置群成员角色

把成员设为管理员，或把管理员改回普通成员。每个群最多 20 个管理员。群主只能通过转让群主产生，不能用这个接口设置或改变。

管理员被改回普通成员时，他生成的入群链接随之失效。被封禁的群也可以设置。

PUT/{org_name}/{app_name}/groups/{group_id}/members/{username}/role

路径参数

org_name、app_name 见接入概述。

参数	类型	说明
`group_id`	String	群 ID
`username`	String	成员的用户名

请求体

字段	类型	必填	说明
`role`	String	是	`admin` 管理员，或 `member` 普通成员。与当前角色相同时不做任何改变，`changed` 为 `false`

请求示例

bash

curl -X PUT "$IM_API/$ORG/$APP/groups/99582624883802112/members/wangwu/role" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "admin"
  }'

响应

成功返回 200 OK，字段同修改群成员资料。

json

{
  "member": {
    "username": "wangwu",
    "nickname": "王五",
    "avatar_url": "https://cdn.example.com/avatar/wangwu.png",
    "role": "admin",
    "group_nickname": "",
    "attributes": null,
    "muted": false,
    "muted_until": null,
    "joined_via": "create",
    "inviter": null,
    "joined_at": "2026-10-02T19:05:47.929Z"
  },
  "changed": true,
  "member_version": 7
}

错误

HTTP 状态码	`code`	说明
400	`invalid_argument`	`role` 不是 `admin` 或 `member`；目标用户是群主
403	`not_group_member`	这个用户不是群成员
404	`not_found`	群不存在或已解散，或用户不存在
409	`limit_exceeded`	`details.reason` 为 `admin_limit`：管理员已有 20 个

禁言群成员

禁止一个成员在本群发言，可以指定时长，也可以永久禁言，到期自动解除。被禁言的成员仍然可以看到群消息，在客户端发送群消息时返回 403 group_muted。管理员也可以被禁言，并且不受全员禁言对管理员的豁免；群主不能被禁言。

群内禁言只影响本群。要禁止用户在所有会话中发言，请使用全局禁言。服务端以成员的身份发送消息时不受群内禁言的限制。

对已被禁言的成员再次禁言时，按新的时长重新计算到期时间（可以延长，也可以缩短）。以下情况视为重复提交，不做任何改变，changed 为 false：已经永久禁言时再次永久禁言；限时禁言的新到期时间与原来的相差不超过 1 分钟（如超时重试）。被封禁的群也可以禁言。

PUT/{org_name}/{app_name}/groups/{group_id}/members/{username}/mute

路径参数

org_name、app_name 见接入概述。

参数	类型	说明
`group_id`	String	群 ID
`username`	String	成员的用户名

请求体

请求体可以省略，省略时永久禁言。

字段	类型	必填	说明
`duration_seconds`	Number	否	禁言时长，单位为秒，1 到 315360000（10 年）。省略或为 `null` 表示永久禁言

请求示例

bash

curl -X PUT "$IM_API/$ORG/$APP/groups/99582624883802112/members/sunqi/mute" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "duration_seconds": 3600
  }'

响应

成功返回 200 OK，字段同修改群成员资料。永久禁言时 muted 为 true、muted_until 为 null。

json

{
  "member": {
    "username": "sunqi",
    "nickname": "孙七",
    "avatar_url": "https://cdn.example.com/avatar/sunqi.png",
    "role": "member",
    "group_nickname": "",
    "attributes": null,
    "muted": true,
    "muted_until": "2026-10-02T20:07:35.934Z",
    "joined_via": "server",
    "inviter": null,
    "joined_at": "2026-10-02T19:06:42.699Z"
  },
  "changed": true,
  "member_version": 8
}

错误

HTTP 状态码	`code`	说明
400	`invalid_argument`	`duration_seconds` 超出范围
403	`permission_denied`	目标用户是群主，不能禁言
403	`not_group_member`	这个用户不是群成员
404	`not_found`	群不存在或已解散，或用户不存在

解除群成员禁言

提前解除成员在本群的禁言。成员没有被禁言（或禁言已到期）时不做任何改变，changed 为 false。全员禁言要另行关闭。被封禁的群也可以解除。

DELETE/{org_name}/{app_name}/groups/{group_id}/members/{username}/mute

路径参数

org_name、app_name 见接入概述。

参数	类型	说明
`group_id`	String	群 ID
`username`	String	成员的用户名

请求示例

bash

curl -X DELETE "$IM_API/$ORG/$APP/groups/99582624883802112/members/zhaoliu/mute" \
  -H "Authorization: Bearer $APP_TOKEN"

响应

成功返回 200 OK，字段同修改群成员资料。

json

{
  "member": {
    "username": "zhaoliu",
    "nickname": "赵六",
    "avatar_url": "https://cdn.example.com/avatar/zhaoliu.png",
    "role": "member",
    "group_nickname": "",
    "attributes": null,
    "muted": false,
    "muted_until": null,
    "joined_via": "server",
    "inviter": null,
    "joined_at": "2026-10-02T19:06:42.699Z"
  },
  "changed": true,
  "member_version": 10
}

错误

HTTP 状态码	`code`	说明
403	`not_group_member`	这个用户不是群成员
404	`not_found`	群不存在或已解散，或用户不存在

数据结构

群成员对象

字段	类型	说明
`username`	String	用户名
`nickname`	String	用户资料中的昵称，没有时为空字符串
`avatar_url`	String	用户资料中的头像地址，没有时为空字符串
`role`	String	角色：`owner` 群主，`admin` 管理员，`member` 普通成员
`group_nickname`	String	本群的群昵称，没有时为空字符串
`attributes`	Object	成员属性，字符串键值对；没有时为 `null`
`muted`	Boolean	当前是否被禁言（不含全员禁言）
`muted_until`	String	禁言的到期时间；永久禁言或没有被禁言时为 `null`
`joined_via`	String	加入方式：`create`、`server`、`invite`、`apply` 或 `link`，见加入群的方式
`inviter`	String	邀请人的用户名：被邀请加入时为邀请人，通过入群链接加入时为生成链接的人；其他方式或邀请人已被删除时为 `null`
`joined_at`	String	加入群的时间

json

{
  "username": "sunqi",
  "nickname": "孙七",
  "avatar_url": "https://cdn.example.com/avatar/sunqi.png",
  "role": "member",
  "group_nickname": "",
  "attributes": null,
  "muted": false,
  "muted_until": null,
  "joined_via": "invite",
  "inviter": "lisi",
  "joined_at": "2026-10-02T19:10:46.913Z"
}

批量操作结果

创建群的 results、批量添加群成员和批量移出群成员的 results 中，每项为一个用户的结果。成功的项只有 username 和 status；失败的项没有 status，带 code 和 message，部分错误另有 details。

字段	类型	说明
`username`	String	用户名（小写）
`status`	String	成功时的结果：`joined` 已加入，`already_member` 原本就是成员，`removed` 已移出，`not_member` 原本就不是成员
`code`	String	失败时的错误码，见下表
`message`	String	失败时的错误说明
`details`	Object	失败的详细原因，只有部分错误带这个字段

`code`	`details.reason`	说明
`not_found`		用户不存在
`permission_denied`	`group_blacklisted`	用户在群黑名单中，不能加入
`permission_denied`		不能移出群主
`limit_exceeded`	`group_member_limit`	群人数已达上限
`limit_exceeded`	`user_group_limit`	这个用户加入的群数已达上限

群成员 ​

查询群成员列表 ​

路径参数 ​

查询参数 ​

请求示例 ​

响应 ​

错误 ​

批量添加群成员 ​

路径参数 ​

请求体 ​

请求示例 ​

响应 ​

错误 ​

批量移出群成员 ​

路径参数 ​

请求体 ​

请求示例 ​

响应 ​

错误 ​

查询群成员 ​

路径参数 ​

请求示例 ​

响应 ​

错误 ​

修改群成员资料 ​

路径参数 ​

请求体 ​

请求示例 ​

响应 ​

错误 ​

设置群成员角色 ​

路径参数 ​

请求体 ​

请求示例 ​

响应 ​

错误 ​

禁言群成员 ​

路径参数 ​

请求体 ​

请求示例 ​

响应 ​

错误 ​

解除群成员禁言 ​

路径参数 ​

请求示例 ​

响应 ​

错误 ​

数据结构 ​

群成员对象 ​

批量操作结果 ​

群成员

查询群成员列表

路径参数

查询参数

请求示例

响应

错误

批量添加群成员

路径参数

请求体

请求示例

响应

错误

批量移出群成员

路径参数

请求体

请求示例

响应

错误

查询群成员

路径参数

请求示例

响应

错误

修改群成员资料

路径参数

请求体

请求示例

响应

错误

设置群成员角色

路径参数

请求体

请求示例

响应

错误

禁言群成员

路径参数

请求体

请求示例

响应

错误

解除群成员禁言

路径参数

请求示例

响应

错误

数据结构

群成员对象

批量操作结果