黑名单

用户可以把不想被打扰的人加入自己的黑名单。拉黑是单向的：A 把 B 拉黑后，限制的是 B 对 A 的操作，A 仍可以给 B 发消息。本页接口路径中的 {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 不受这个开关影响，可以照常管理黑名单，例如在开启拦截前导入数据。
• 用户被删除后，他会自动从别人的黑名单中移除。

黑名单与好友列表一样有版本号，每变化一次加 1。拉黑、移出黑名单的接口返回 changed 和 blacklist_version：changed 为 true 表示这次请求改变了黑名单，blacklist_version 是改变后的版本号；为 false 表示没有改变（如重复拉黑），blacklist_version 是当前的版本号。因此重复调用都返回 200 OK，可以放心重试。

查询黑名单

分页返回用户的黑名单，每页默认 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"
}