Skip to main content
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"]
  }'

{
  "status": "ok"
}

​
Overview

Set (replace) the entire blacklist for a channel. This operation will first remove all existing blacklist entries and then add new ones. If UIDs is empty, the entire blacklist will be cleared.

​
Request Body

​
Required Parameters

​
channel_id
string
required
Channel ID, cannot be empty or contain special characters
​
channel_type
integer
required
Channel type
  • 1 - Person channel
  • 2 - Group channel

​
Optional Parameters

​
uids
array
List of user IDs to set as blacklist. If empty, clears the entire blacklist.
​
uids[]
string
User ID
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"]
  }'

{
  "status": "ok"
}

​
Response Fields

​
status
string
required
Operation status, returns "ok" on success

​
Status Codes

Status CodeDescription
200Blacklist set successfully
400Request parameter error
403No management permission
404Channel does not exist
500Internal server error

​
Functionality

​
Set Operation

The set operation performs the following steps:
  1. Clear Existing Blacklist: Remove all existing blacklist entries for the channel
  2. Add New Entries: Add the provided user ID list to the blacklist
  3. Delete Conversations: Automatically delete related conversations for blacklisted users
  4. Update Permissions: Take effect immediately, blacklisted users cannot send or receive messages

​
Clear Operation

When uids is an empty array:
  • Clear all blacklist entries for the channel
  • Restore normal permissions for all users
  • Does not affect existing conversations

​
Blacklist Mechanism

​
Permission Restrictions

Blacklisted users are subject to the following restrictions:
RestrictionDescriptionScope
Cannot Send MessagesBlocked from sending any messages to the channelAll message types
Cannot Receive MessagesWill not receive messages from the channelAll channel messages
Conversation DeletionRelated conversations are automatically deletedExcept live channels
Permission RevocationLose all channel-related permissionsComplete isolation

​
Special Cases

  • Live Channels: Do not process conversation deletion
  • Person Channels: Do not support blacklist operations
  • System Users: May have special permissions, not affected by blacklist

​
Use Cases

​
Batch Management

# Set new blacklist, replacing all existing entries
curl -X POST "/channel/blacklist_set" -d '{
  "channel_id": "group123",
  "channel_type": 2,
  "uids": ["spammer1", "spammer2", "violator1"]
}'

​
Clear Blacklist

# Clear all blacklist, restore all user permissions
curl -X POST "/channel/blacklist_set" -d '{
  "channel_id": "group123",
  "channel_type": 2,
  "uids": []
}'

​
Reset Blacklist

# Completely reset blacklist to new user list
curl -X POST "/channel/blacklist_set" -d '{
  "channel_id": "group123",
  "channel_type": 2,
  "uids": ["new_blocked_user"]
}'

​
Comparison with Other Blacklist Operations

OperationFunctionUse Case
blacklist_addAdd users to existing blacklistIncrementally add violating users
blacklist_setReplace entire blacklistBatch management, reset blacklist
blacklist_removeRemove specific users from blacklistLift restrictions on specific users

​
Best Practices

  1. Use Carefully: Set operation clears all existing blacklist, ensure this is intended behavior
  2. Backup Existing Data: Get current blacklist before setting as backup
  3. Permission Verification: Ensure operator has sufficient management permissions
  4. Log Recording: Record blacklist changes for auditing
  5. Notification Mechanism: Consider notifying relevant administrators of blacklist changes
  6. Test Validation: Thoroughly test before using in production environment

​
Error Handling

​
Common Errors

Error MessageCauseSolution
Channel ID cannot be emptyNo channel ID providedEnsure valid channel ID is provided
Channel type cannot be 0Invalid channel typeUse valid channel type (1 or 2)
Channel ID cannot contain special charactersInvalid channel ID formatUse alphanumeric characters and underscores
Remove all blacklist failedClear operation failedCheck channel status and permissions
Add blacklist failedAdd operation failedCheck user ID validity