curl -X POST "http://localhost:5001/channel/blacklist_set" \
-H "Content-Type: application/json" \
-d '{
"channel_id": "group123",
"channel_type": 2,
"uids": ["user1", "user2", "user3"]
}'
curl -X POST "http://localhost:5001/channel/blacklist_set" \
-H "Content-Type: application/json" \
-d '{
"channel_id": "group123",
"channel_type": 2,
"uids": []
}'
// 设置黑名单
const response = await fetch('http://localhost:5001/channel/blacklist_set', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
channel_id: 'group123',
channel_type: 2,
uids: ['user1', 'user2', 'user3']
})
});
const data = await response.json();
console.log(data);
// 清空黑名单
const clearResponse = await fetch('http://localhost:5001/channel/blacklist_set', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
channel_id: 'group123',
channel_type: 2,
uids: []
})
});
import requests
# 设置黑名单
data = {
"channel_id": "group123",
"channel_type": 2,
"uids": ["user1", "user2", "user3"]
}
response = requests.post('http://localhost:5001/channel/blacklist_set', json=data)
result = response.json()
print(result)
# 清空黑名单
clear_data = {
"channel_id": "group123",
"channel_type": 2,
"uids": []
}
clear_response = requests.post('http://localhost:5001/channel/blacklist_set', json=clear_data)
clear_result = clear_response.json()
print(clear_result)
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
func main() {
// 设置黑名单
data := map[string]interface{}{
"channel_id": "group123",
"channel_type": 2,
"uids": []string{"user1", "user2", "user3"},
}
jsonData, _ := json.Marshal(data)
resp, err := http.Post(
"http://localhost:5001/channel/blacklist_set",
"application/json",
bytes.NewBuffer(jsonData),
)
if err != nil {
panic(err)
}
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Printf("%+v\n", result)
// 清空黑名单
clearData := map[string]interface{}{
"channel_id": "group123",
"channel_type": 2,
"uids": []string{},
}
clearJsonData, _ := json.Marshal(clearData)
clearResp, err := http.Post(
"http://localhost:5001/channel/blacklist_set",
"application/json",
bytes.NewBuffer(clearJsonData),
)
if err != nil {
panic(err)
}
defer clearResp.Body.Close()
var clearResult map[string]interface{}
json.NewDecoder(clearResp.Body).Decode(&clearResult)
fmt.Printf("%+v\n", clearResult)
}
{
"status": "ok"
}
频道管理
设置频道黑名单
设置(替换)频道的完整黑名单
POST
/
channel
/
blacklist_set
curl -X POST "http://localhost:5001/channel/blacklist_set" \
-H "Content-Type: application/json" \
-d '{
"channel_id": "group123",
"channel_type": 2,
"uids": ["user1", "user2", "user3"]
}'
curl -X POST "http://localhost:5001/channel/blacklist_set" \
-H "Content-Type: application/json" \
-d '{
"channel_id": "group123",
"channel_type": 2,
"uids": []
}'
// 设置黑名单
const response = await fetch('http://localhost:5001/channel/blacklist_set', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
channel_id: 'group123',
channel_type: 2,
uids: ['user1', 'user2', 'user3']
})
});
const data = await response.json();
console.log(data);
// 清空黑名单
const clearResponse = await fetch('http://localhost:5001/channel/blacklist_set', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
channel_id: 'group123',
channel_type: 2,
uids: []
})
});
import requests
# 设置黑名单
data = {
"channel_id": "group123",
"channel_type": 2,
"uids": ["user1", "user2", "user3"]
}
response = requests.post('http://localhost:5001/channel/blacklist_set', json=data)
result = response.json()
print(result)
# 清空黑名单
clear_data = {
"channel_id": "group123",
"channel_type": 2,
"uids": []
}
clear_response = requests.post('http://localhost:5001/channel/blacklist_set', json=clear_data)
clear_result = clear_response.json()
print(clear_result)
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
func main() {
// 设置黑名单
data := map[string]interface{}{
"channel_id": "group123",
"channel_type": 2,
"uids": []string{"user1", "user2", "user3"},
}
jsonData, _ := json.Marshal(data)
resp, err := http.Post(
"http://localhost:5001/channel/blacklist_set",
"application/json",
bytes.NewBuffer(jsonData),
)
if err != nil {
panic(err)
}
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Printf("%+v\n", result)
// 清空黑名单
clearData := map[string]interface{}{
"channel_id": "group123",
"channel_type": 2,
"uids": []string{},
}
clearJsonData, _ := json.Marshal(clearData)
clearResp, err := http.Post(
"http://localhost:5001/channel/blacklist_set",
"application/json",
bytes.NewBuffer(clearJsonData),
)
if err != nil {
panic(err)
}
defer clearResp.Body.Close()
var clearResult map[string]interface{}
json.NewDecoder(clearResp.Body).Decode(&clearResult)
fmt.Printf("%+v\n", clearResult)
}
{
"status": "ok"
}
概述
设置(替换)频道的完整黑名单。此操作会先清除所有现有黑名单条目,然后添加新的条目。如果UIDs为空,则清空整个黑名单。请求体
必传参数
频道ID,不能为空或包含特殊字符
频道类型
1- 个人频道2- 群组频道
可选参数
curl -X POST "http://localhost:5001/channel/blacklist_set" \
-H "Content-Type: application/json" \
-d '{
"channel_id": "group123",
"channel_type": 2,
"uids": ["user1", "user2", "user3"]
}'
curl -X POST "http://localhost:5001/channel/blacklist_set" \
-H "Content-Type: application/json" \
-d '{
"channel_id": "group123",
"channel_type": 2,
"uids": []
}'
// 设置黑名单
const response = await fetch('http://localhost:5001/channel/blacklist_set', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
channel_id: 'group123',
channel_type: 2,
uids: ['user1', 'user2', 'user3']
})
});
const data = await response.json();
console.log(data);
// 清空黑名单
const clearResponse = await fetch('http://localhost:5001/channel/blacklist_set', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
channel_id: 'group123',
channel_type: 2,
uids: []
})
});
import requests
# 设置黑名单
data = {
"channel_id": "group123",
"channel_type": 2,
"uids": ["user1", "user2", "user3"]
}
response = requests.post('http://localhost:5001/channel/blacklist_set', json=data)
result = response.json()
print(result)
# 清空黑名单
clear_data = {
"channel_id": "group123",
"channel_type": 2,
"uids": []
}
clear_response = requests.post('http://localhost:5001/channel/blacklist_set', json=clear_data)
clear_result = clear_response.json()
print(clear_result)
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
func main() {
// 设置黑名单
data := map[string]interface{}{
"channel_id": "group123",
"channel_type": 2,
"uids": []string{"user1", "user2", "user3"},
}
jsonData, _ := json.Marshal(data)
resp, err := http.Post(
"http://localhost:5001/channel/blacklist_set",
"application/json",
bytes.NewBuffer(jsonData),
)
if err != nil {
panic(err)
}
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Printf("%+v\n", result)
// 清空黑名单
clearData := map[string]interface{}{
"channel_id": "group123",
"channel_type": 2,
"uids": []string{},
}
clearJsonData, _ := json.Marshal(clearData)
clearResp, err := http.Post(
"http://localhost:5001/channel/blacklist_set",
"application/json",
bytes.NewBuffer(clearJsonData),
)
if err != nil {
panic(err)
}
defer clearResp.Body.Close()
var clearResult map[string]interface{}
json.NewDecoder(clearResp.Body).Decode(&clearResult)
fmt.Printf("%+v\n", clearResult)
}
{
"status": "ok"
}
响应字段
操作状态,成功时返回
"ok"状态码
| 状态码 | 说明 |
|---|---|
| 200 | 黑名单设置成功 |
| 400 | 请求参数错误 |
| 403 | 没有管理权限 |
| 404 | 频道不存在 |
| 500 | 服务器内部错误 |
功能说明
设置操作
设置操作会执行以下步骤:- 清除现有黑名单:删除频道的所有现有黑名单条目
- 添加新条目:将提供的用户ID列表添加到黑名单
- 删除会话:自动删除黑名单用户的相关会话
- 权限更新:立即生效,黑名单用户无法发送或接收消息
清空操作
当uids 为空数组时:
- 清除频道的所有黑名单条目
- 恢复所有用户的正常权限
- 不影响现有会话
黑名单机制
权限限制
黑名单用户受到以下限制:| 限制 | 说明 | 影响范围 |
|---|---|---|
| 无法发送消息 | 被阻止向频道发送任何消息 | 所有消息类型 |
| 无法接收消息 | 不会收到频道内的消息 | 所有频道消息 |
| 会话删除 | 相关会话被自动删除 | 除直播频道外 |
| 权限剥夺 | 失去所有频道相关权限 | 完全隔离 |
特殊情况
- 直播频道:不处理会话删除操作
- 个人频道:不支持黑名单操作
- 系统用户:可能有特殊权限,不受黑名单影响
使用场景
批量管理
# 设置新的黑名单,替换所有现有条目
curl -X POST "/channel/blacklist_set" -d '{
"channel_id": "group123",
"channel_type": 2,
"uids": ["spammer1", "spammer2", "violator1"]
}'
清空黑名单
# 清空所有黑名单,恢复所有用户权限
curl -X POST "/channel/blacklist_set" -d '{
"channel_id": "group123",
"channel_type": 2,
"uids": []
}'
重置黑名单
# 完全重置黑名单为新的用户列表
curl -X POST "/channel/blacklist_set" -d '{
"channel_id": "group123",
"channel_type": 2,
"uids": ["new_blocked_user"]
}'
与其他黑名单操作的区别
| 操作 | 功能 | 适用场景 |
|---|---|---|
blacklist_add | 添加用户到现有黑名单 | 增量添加违规用户 |
blacklist_set | 替换整个黑名单 | 批量管理、重置黑名单 |
blacklist_remove | 从黑名单移除特定用户 | 解除特定用户的限制 |
最佳实践
- 谨慎使用:设置操作会清除所有现有黑名单,确保这是预期行为
- 备份现有数据:在设置前获取当前黑名单列表作为备份
- 权限验证:确保操作者有足够的管理权限
- 日志记录:记录黑名单变更以便审计
- 通知机制:考虑通知相关管理员黑名单变更
- 测试验证:在生产环境使用前进行充分测试
错误处理
常见错误
| 错误信息 | 原因 | 解决方案 |
|---|---|---|
| 频道ID不能为空 | 未提供频道ID | 确保提供有效的频道ID |
| 频道类型不能为0 | 频道类型无效 | 使用有效的频道类型(1或2) |
| 频道ID不能包含特殊字符 | 频道ID格式无效 | 使用字母数字和下划线 |
| 移除所有黑名单失败 | 清除操作失败 | 检查频道状态和权限 |
| 添加黑名单失败 | 添加操作失败 | 检查用户ID有效性 |
相关接口
⌘I

