黑名單

使用者可以把不想被打擾的人加入黑名單。拉黑是單向的：A 拉黑 B 後，限制的是 B 對 A 的操作，A 仍能給 B 發訊息。使用者通常在客戶端自己拉黑；你的服務端可以代使用者管理，或從其他系統匯入。

例如，替 alice 拉黑 spammer：

curl -X PUT "$IM_API/$ORG/$APP/users/alice/blacklist/spammer" \
  -H "Authorization: Bearer $APP_TOKEN"

路徑中的 {username} 是黑名單的所有者（A），{target} 是被拉黑的人（B）。

拉黑後	說明
B 不能給 A 發單聊訊息	B 在客戶端傳送時返回 403 user_blocked；單聊中的表情回應、置頂訊息同樣被攔截，“正在輸入”提示不會送達 A。你的服務端以 B 的身份透過 REST API 代發的訊息不受限制
B 不能向 A 傳送好友申請	返回 403 user_blocked，見好友申請
B 不能邀請 A 入群	B 在客戶端邀請 A 入群（包括建群時邀請）時，A 這一項失敗，錯誤為 user_blocked
不解除好友關係	拉黑前是好友的，B 仍在 A 的好友列表中；A 移出黑名單後兩人照常聊天，不必重新加好友
撤回 A 發給 B 的申請	A 發給 B、尚未處理的好友申請被一併撤回，B 不能再同意它。B 發給 A 的申請不受影響，A 仍可以同意或拒絕
不影響群聊和聊天室	群聊和聊天室中的訊息不受個人黑名單影響

• 不通知被拉黑的人：所有者的線上裝置收到 blacklist.changed，被拉黑的人什麼也收不到。查詢介面也只回答“我是否拉黑了對方”，不回答“對方是否拉黑了我”。
• 上限：每人最多拉黑 1000 人。
• 攔截開關：執行策略的 user_blacklist_enabled（預設開啟，見執行策略）關閉後，黑名單資料保留但不再攔截上表中的操作；使用者在客戶端不能再拉黑別人（403 permission_denied），檢視和移出照常。服務端 REST API 不受開關影響，可以在開啟攔截前先匯入資料。
• 使用者被刪除後，自動從別人的黑名單中移除。
• 可以放心重試：拉黑、移出的介面返回 changed 和 blacklist_version（黑名單的版本號，每變化一次加 1）。重複拉黑等沒有改變的情況返回 200 OK，changed 為 false。

查詢黑名單

分頁返回使用者的黑名單，每頁預設 100 個、最多 500 個。

GET/{org_name}/{app_name}/users/{username}/blacklist

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
username	String	黑名單的所有者

查詢引數

引數	型別	必填	說明
limit	Number	否	每頁條數，預設 100，取值 1 到 500
cursor	String	否	下一頁的遊標，第一頁不傳，見分頁
known_version	Number	否	你儲存的黑名單版本號，非負整數，只在請求第一頁時生效。與當前版本號相同時只返回列表頭（not_modified 為 true），不返回 items 和 next_cursor

請求示例

curl "$IM_API/$ORG/$APP/users/bob/blacklist" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK：

欄位	型別	說明
version	Number	黑名單當前的版本號，從未拉黑過別人的使用者為 0
not_modified	Boolean	是否與請求中的 known_version 相同。為 true 時響應只有 version、not_modified、count、max_count 四個欄位
count	Number	當前黑名單中的人數
max_count	Number	黑名單人數上限，固定為 1000
items	Array<Object>	本頁的黑名單，每項為黑名單項物件
next_cursor	String	下一頁的遊標，為 null 時沒有下一頁

{
  "version": 4,
  "not_modified": false,
  "count": 2,
  "max_count": 1000,
  "items": [
    { "username": "dave", "nickname": "戴夫", "avatar_url": "", "created_at": "2026-10-02T19:10:16.494Z" },
    { "username": "erin", "nickname": "艾琳", "avatar_url": "", "created_at": "2026-10-02T19:10:16.511Z" }
  ],
  "next_cursor": null
}

錯誤

HTTP 狀態碼	code	說明
400	invalid_argument	limit 不在 1 到 500 之間、known_version 不是非負整數，或 cursor 無效
404	not_found	使用者不存在或已刪除

拉黑使用者

把 {target} 加入 {username} 的黑名單，效果見本頁開頭。已經在黑名單中時同樣返回 200 OK，changed 為 false。

PUT/{org_name}/{app_name}/users/{username}/blacklist/{target}

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
username	String	黑名單的所有者
target	String	要拉黑的使用者名稱，不能是 {username} 本人

請求示例

curl -X PUT "$IM_API/$ORG/$APP/users/frank/blacklist/alice" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK：

欄位	型別	說明
entry	Object	這一項黑名單項物件。已經在黑名單中時為原來的那一項，created_at 不變
changed	Boolean	這次請求是否改變了黑名單
blacklist_version	Number	黑名單的版本號：changed 為 true 時是改變後的版本號，為 false 時是當前的版本號

{
  "entry": {
    "username": "alice",
    "nickname": "爱丽丝",
    "avatar_url": "",
    "created_at": "2026-10-02T19:09:27.367Z"
  },
  "changed": true,
  "blacklist_version": 1
}

錯誤

HTTP 狀態碼	code	說明
400	invalid_argument	{target} 是 {username} 本人
404	not_found	{username} 或 {target} 不存在或已刪除
409	limit_exceeded	黑名單已滿 1000 人，details.reason 為 blacklist_limit

移出黑名單

把 {target} 移出 {username} 的黑名單。本來就不在黑名單中時同樣返回 200 OK，changed 為 false。

DELETE/{org_name}/{app_name}/users/{username}/blacklist/{target}

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
username	String	黑名單的所有者
target	String	要移出的使用者名稱

請求示例

curl -X DELETE "$IM_API/$ORG/$APP/users/bob/blacklist/dave" \
  -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK：

欄位	型別	說明
changed	Boolean	這次請求是否改變了黑名單
blacklist_version	Number	黑名單的版本號

{
  "changed": true,
  "blacklist_version": 2
}

錯誤

HTTP 狀態碼	code	說明
400	invalid_argument	{target} 是 {username} 本人
404	not_found	{username} 或 {target} 不存在或已刪除

批次拉黑

為一個使用者一次拉黑最多 100 個使用者，每一項的規則與拉黑使用者相同，原本就在黑名單中的也算成功。各項分別處理、互不影響，見批次介面。按項數計入應用的呼叫額度。

POST/{org_name}/{app_name}/users/{username}/blacklist/batch

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
username	String	黑名單的所有者

請求體

欄位	型別	必填	說明
usernames	Array<String>	是	要拉黑的使用者名稱，1 到 100 個

請求示例

curl -X POST "$IM_API/$ORG/$APP/users/bob/blacklist/batch" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "usernames": ["dave", "erin", "nobody", "bob"]
  }'

響應

成功返回 200 OK。同一個使用者名稱出現多次時不去重，按出現的次數逐個處理。

欄位	型別	說明
added	Array<String>	拉黑成功的使用者名稱，包括原本就在黑名單中的
failed	Array<Object>	失敗的項，每項為 username（小寫）、code、message 和可選的 details，錯誤與拉黑使用者相同

{
  "added": ["dave", "erin"],
  "failed": [
    { "username": "nobody", "code": "not_found", "message": "用户不存在" },
    { "username": "bob", "code": "invalid_argument", "message": "不能把自己加入黑名单" }
  ]
}

批次介面不返回 changed 和版本號。

錯誤

HTTP 狀態碼	code	說明
400	invalid_argument	usernames 為空或超過 100 個
404	not_found	{username} 不存在或已刪除

批次移出黑名單

為一個使用者一次移出最多 100 個使用者，每一項的規則與移出黑名單相同，原本就不在黑名單中的也算成功。按項數計入應用的呼叫額度。

POST/{org_name}/{app_name}/users/{username}/blacklist/batch-delete

路徑引數

org_name、app_name 見接入概述。

引數	型別	說明
username	String	黑名單的所有者

請求體

欄位	型別	必填	說明
usernames	Array<String>	是	要移出的使用者名稱，1 到 100 個

請求示例

curl -X POST "$IM_API/$ORG/$APP/users/bob/blacklist/batch-delete" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "usernames": ["dave", "carol", "nobody"]
  }'

響應

成功返回 200 OK：

欄位	型別	說明
removed	Array<String>	移出成功的使用者名稱，包括原本就不在黑名單中的
failed	Array<Object>	失敗的項，格式同批次拉黑

{
  "removed": ["dave", "carol"],
  "failed": [
    { "username": "nobody", "code": "not_found", "message": "用户不存在" }
  ]
}

錯誤

HTTP 狀態碼	code	說明
400	invalid_argument	usernames 為空或超過 100 個
404	not_found	{username} 不存在或已刪除

資料結構

黑名單項物件

欄位	型別	說明
username	String	被拉黑的使用者名稱
nickname	String	被拉黑使用者的暱稱，沒有設定時為空字串
avatar_url	String	被拉黑使用者的頭像地址，沒有設定時為空字串
created_at	String	拉黑的時間

{
  "username": "alice",
  "nickname": "爱丽丝",
  "avatar_url": "",
  "created_at": "2026-10-02T19:09:27.367Z"
}