群黑名單

不讓某些使用者進入一個群。常用於踢出違規成員後防止他再回來。

例如，把 sunqi 踢出群並且不讓他再加入：

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

使用者被加入群黑名單後：

• 如果他在群裡，同時被移出群，他和群的線上成員會實時收到通知；
• 他不能再加入這個群：不能申請加入、不能被成員邀請、不能透過入群連結加入，服務端新增成員時這一項也會失敗（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"
}