概述
设置(替换)频道的完整白名单。此操作会先清除所有现有白名单条目,然后添加新的条目。如果UIDs为空,则清空整个白名单。请求体
必传参数
频道ID,不能为空或包含特殊字符
频道类型
1- 个人频道2- 群组频道
可选参数
响应字段
操作状态,成功时返回
"ok"状态码
| 状态码 | 说明 |
|---|---|
| 200 | 白名单设置成功 |
| 400 | 请求参数错误 |
| 403 | 没有管理权限 |
| 404 | 频道不存在 |
| 500 | 服务器内部错误 |
功能说明
设置操作
设置操作会执行以下步骤:- 清除现有白名单:删除频道的所有现有白名单条目
- 添加新条目:将提供的用户ID列表添加到白名单
- 权限更新:立即生效,只有白名单用户可以发送消息(如果启用白名单模式)
- 会话管理:为个人频道自动创建相关会话
清空操作
当uids 为空数组时:
- 清除频道的所有白名单条目
- 恢复所有用户的正常权限
- 禁用白名单模式
白名单机制
权限特性
白名单用户享有以下特权:| 特权 | 说明 | 适用条件 |
|---|---|---|
| 发送权限 | 可以向频道发送消息 | 启用白名单模式时 |
| 绕过限制 | 绕过某些频道限制 | 根据频道配置 |
| 优先处理 | 消息可能获得优先处理 | 系统配置相关 |
| 会话保障 | 确保会话正常创建 | 个人频道 |
白名单模式
- 启用时:只有白名单用户可以发送消息
- 禁用时:白名单不影响消息发送权限
- 个人频道:白名单用户会自动创建会话
使用场景
批量管理
清空白名单
重置白名单
与其他白名单操作的区别
| 操作 | 功能 | 适用场景 |
|---|---|---|
whitelist_add | 添加用户到现有白名单 | 增量添加特权用户 |
whitelist_set | 替换整个白名单 | 批量管理、重置白名单 |
whitelist_remove | 从白名单移除特定用户 | 移除特定用户的特权 |
权限层级
白名单在权限体系中的位置:冲突处理
| 情况 | 结果 | 说明 |
|---|---|---|
| 同时在黑白名单 | 按黑名单处理 | 黑名单优先级更高 |
| 只在白名单 | 享受白名单权限 | 正常白名单用户 |
| 只在黑名单 | 受黑名单限制 | 正常黑名单用户 |
| 都不在名单 | 普通用户权限 | 按默认权限处理 |
最佳实践
- 谨慎使用:设置操作会清除所有现有白名单,确保这是预期行为
- 备份现有数据:在设置前获取当前白名单列表作为备份
- 权限验证:确保操作者有足够的管理权限
- 渐进式管理:对于大型频道,考虑渐进式白名单管理
- 监控效果:设置后监控频道活动和用户反馈
- 文档记录:记录白名单变更原因和预期效果
错误处理
常见错误
| 错误信息 | 原因 | 解决方案 |
|---|---|---|
| 频道ID不能为空 | 未提供频道ID | 确保提供有效的频道ID |
| 频道类型不能为0 | 频道类型无效 | 使用有效的频道类型(1或2) |
| 频道ID不能包含特殊字符 | 频道ID格式无效 | 使用字母数字和下划线 |
| 移除所有白名单失败 | 清除操作失败 | 检查频道状态和权限 |
| 添加白名单失败 | 添加操作失败 | 检查用户ID有效性 |
错误恢复策略
监控和分析
性能指标
- 白名单设置成功率
- 操作响应时间
- 用户活跃度变化
- 消息发送量变化
分析维度
- 白名单用户行为分析
- 频道活跃度对比
- 权限变更影响评估
- 用户满意度调查

