跳转到主要内容
POST

概述

设置(替换)频道的完整黑名单。此操作会先清除所有现有黑名单条目,然后添加新的条目。如果UIDs为空,则清空整个黑名单。

请求体

必传参数

channel_id
string
必填
频道ID,不能为空或包含特殊字符
channel_type
integer
必填
频道类型
  • 1 - 个人频道
  • 2 - 群组频道

可选参数

uids
array
要设置为黑名单的用户ID列表。如果为空,则清空整个黑名单。
uids[]
string
用户ID

响应字段

status
string
必填
操作状态,成功时返回 "ok"

状态码

功能说明

设置操作

设置操作会执行以下步骤:
  1. 清除现有黑名单:删除频道的所有现有黑名单条目
  2. 添加新条目:将提供的用户ID列表添加到黑名单
  3. 删除会话:自动删除黑名单用户的相关会话
  4. 权限更新:立即生效,黑名单用户无法发送或接收消息

清空操作

uids 为空数组时:
  • 清除频道的所有黑名单条目
  • 恢复所有用户的正常权限
  • 不影响现有会话

黑名单机制

权限限制

黑名单用户受到以下限制:

特殊情况

  • 直播频道:不处理会话删除操作
  • 个人频道:不支持黑名单操作
  • 系统用户:可能有特殊权限,不受黑名单影响

使用场景

批量管理

清空黑名单

重置黑名单

与其他黑名单操作的区别

最佳实践

  1. 谨慎使用:设置操作会清除所有现有黑名单,确保这是预期行为
  2. 备份现有数据:在设置前获取当前黑名单列表作为备份
  3. 权限验证:确保操作者有足够的管理权限
  4. 日志记录:记录黑名单变更以便审计
  5. 通知机制:考虑通知相关管理员黑名单变更
  6. 测试验证:在生产环境使用前进行充分测试

错误处理

常见错误

相关接口