Set Channel Blacklist

Set (replace) the entire blacklist for a channel

POST /channel/blacklist_set

Try it

Set Blacklist

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"]
  }'

Success Response

{
  "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

Set Blacklist

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"]
  }'

Success Response

{
  "status": "ok"
}

Response Fields

status · string · required

Operation status, returns "ok" on success

Status Codes

Status Code	Description
200	Blacklist set successfully
400	Request parameter error
403	No management permission
404	Channel does not exist
500	Internal 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:

Restriction	Description	Scope
Cannot Send Messages	Blocked from sending any messages to the channel	All message types
Cannot Receive Messages	Will not receive messages from the channel	All channel messages
Conversation Deletion	Related conversations are automatically deleted	Except live channels
Permission Revocation	Lose all channel-related permissions	Complete 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

Operation	Function	Use Case
blacklist_add	Add users to existing blacklist	Incrementally add violating users
blacklist_set	Replace entire blacklist	Batch management, reset blacklist
blacklist_remove	Remove specific users from blacklist	Lift 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 Message	Cause	Solution
Channel ID cannot be empty	No channel ID provided	Ensure valid channel ID is provided
Channel type cannot be 0	Invalid channel type	Use valid channel type (1 or 2)
Channel ID cannot contain special characters	Invalid channel ID format	Use alphanumeric characters and underscores
Remove all blacklist failed	Clear operation failed	Check channel status and permissions
Add blacklist failed	Add operation failed	Check user ID validity

Related APIs

• Add Channel Blacklist - Incrementally add blacklist users
• Remove Channel Blacklist - Remove specific blacklist users
• Add Channel Whitelist - Manage whitelist users