群黑名单

群黑名单用来阻止某些用户进入一个群。用户被加入群黑名单后：

• 如果他在群里，同时被移出群，他和群的在线成员会实时收到通知；
• 他不能再加入这个群：不能申请加入、不能被成员邀请、不能通过入群链接加入，服务端添加成员时这一项也会失败（permission_denied，details.reason 为 group_blacklisted）；
• 他在本群尚未处理的入群申请和邀请立即失效（cancel_cause 为 blacklisted）。

不在群里的用户也可以加入群黑名单，提前阻止他加入。移出群黑名单后，用户不会自动回到群里，需要重新添加或由他重新申请。群黑名单只影响本群，与用户之间的黑名单无关。

每个群的黑名单最多 1000 人。群主不能被加入群黑名单。被封禁的群也可以管理群黑名单。

客户端中的群黑名单

群主和管理员也可以在客户端管理群黑名单。每条记录保存了加入时操作人的身份 created_by_role：管理员在客户端只能移出管理员加入的记录，群主加入的和服务端加入的只有群主能在客户端移出。服务端接口可以移出任何记录。

查询群黑名单

分页返回群黑名单。账号已被删除的用户不在列表中，一页的条数可能少于 limit，是否还有下一页以 next_cursor 为准。

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

路径参数

org_name、app_name 见接入概述。

参数	类型	说明
group_id	String	群 ID

查询参数

参数	类型	必填	说明
limit	Number	否	每页条数，默认 20，取值 1 到 100
cursor	String	否	下一页的游标，见分页

请求示例

curl -X GET "$IM_API/$ORG/$APP/groups/99582688326844416/blacklist" \
  -H "Authorization: Bearer $APP_TOKEN"

响应

成功返回 200 OK，items 中每项为一个群黑名单记录，next_cursor 为下一页的游标，没有下一页时为 null。

{
  "items": [
    {
      "username": "zhouba",
      "nickname": "周八",
      "avatar_url": "https://cdn.example.com/avatar/zhouba.png",
      "reason": "刷屏",
      "created_by": "wangwu",
      "created_by_role": "admin",
      "created_at": "2026-10-02T19:21:57.068Z"
    },
    {
      "username": "zhengshi",
      "nickname": "郑十",
      "avatar_url": "https://cdn.example.com/avatar/zhengshi.png",
      "reason": "发布广告",
      "created_by": null,
      "created_by_role": "server",
      "created_at": "2026-10-02T19:10:34.181Z"
    }
  ],
  "next_cursor": null
}

错误

HTTP 状态码	code	说明
400	invalid_argument	limit 超出范围
404	not_found	群不存在

将用户加入群黑名单

把一个用户加入群黑名单；他是群成员时同时被移出群，群会话中出现成员被移出的提示消息。

用户已在群黑名单中时不做任何改变，原来的记录（包括原因和操作人）保持不变，changed 为 false，因此可以放心重试。

PUT/{org_name}/{app_name}/groups/{group_id}/blacklist/{username}

路径参数

org_name、app_name 见接入概述。

参数	类型	说明
group_id	String	群 ID
username	String	要加入群黑名单的用户名

请求体

请求体可以省略。

字段	类型	必填	说明
reason	String	否	原因，最长 256 个字符，不能包含换行等控制字符。群主和管理员在客户端查看群黑名单时可以看到

请求示例

curl -X PUT "$IM_API/$ORG/$APP/groups/99582624883802112/blacklist/zhaoliu" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "多次发布广告"
  }'

响应

成功返回 200 OK：

字段	类型	说明
entry	Object	这个用户的群黑名单记录；用户原本就在群黑名单中时为原来的记录
changed	Boolean	这次请求是否把用户新加入了群黑名单
member_version	Number	成员列表的版本号。用户原本是群成员、被移出时为移出后的新版本号，否则为当前的版本号

{
  "entry": {
    "username": "zhaoliu",
    "nickname": "赵六",
    "avatar_url": "https://cdn.example.com/avatar/zhaoliu.png",
    "reason": "多次发布广告",
    "created_by": null,
    "created_by_role": "server",
    "created_at": "2026-10-02T19:22:03.134Z"
  },
  "changed": true,
  "member_version": 26
}

错误

HTTP 状态码	code	说明
400	invalid_argument	reason 超过 256 个字符或包含控制字符
403	permission_denied	目标用户是群主，不能加入群黑名单
404	not_found	群不存在或已解散，或用户不存在
409	limit_exceeded	details.reason 为 group_blacklist_limit：群黑名单已有 1000 人

将用户移出群黑名单

把一个用户移出群黑名单，之后他可以重新加入这个群。移出群黑名单不会把他加回群里。用户不在群黑名单中时不做任何改变，changed 为 false。

DELETE/{org_name}/{app_name}/groups/{group_id}/blacklist/{username}

路径参数

org_name、app_name 见接入概述。

参数	类型	说明
group_id	String	群 ID
username	String	要移出群黑名单的用户名

请求示例

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

响应

成功返回 200 OK：

字段	类型	说明
changed	Boolean	这次请求是否把用户移出了群黑名单
member_version	Number	当前的成员列表版本号（移出群黑名单不改变成员列表）

{
  "changed": true,
  "member_version": 26
}

错误

HTTP 状态码	code	说明
404	not_found	群不存在或已解散，或用户不存在

数据结构

群黑名单记录

字段	类型	说明
username	String	被加入群黑名单的用户名
nickname	String	用户资料中的昵称，没有时为空字符串
avatar_url	String	用户资料中的头像地址，没有时为空字符串
reason	String	原因，没有时为空字符串
created_by	String	在客户端执行操作的群主或管理员的用户名；由服务端或控制台加入、或操作人已被删除时为 null
created_by_role	String	加入时操作人的身份：owner 群主，admin 管理员，server 服务端或控制台。之后转让群主、角色变化都不会改变它
created_at	String	加入群黑名单的时间

{
  "username": "zhouba",
  "nickname": "周八",
  "avatar_url": "https://cdn.example.com/avatar/zhouba.png",
  "reason": "刷屏",
  "created_by": "wangwu",
  "created_by_role": "admin",
  "created_at": "2026-10-02T19:21:57.068Z"
}