Skip to main content
POST
/
channel
/
whitelist_set
curl -X POST "http://localhost:5001/channel/whitelist_set" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "group123",
    "channel_type": 2,
    "uids": ["user1", "user2", "user3"]
  }'

{
  "status": "ok"
}

​
Overview

Set (replace) the entire whitelist for a channel. This operation will first remove all existing whitelist entries and then add new ones. If UIDs is empty, the entire whitelist 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 whitelist. If empty, clears the entire whitelist.
​
uids[]
string
User ID
curl -X POST "http://localhost:5001/channel/whitelist_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
200Whitelist 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 Whitelist: Remove all existing whitelist entries for the channel
  2. Add New Entries: Add the provided user ID list to the whitelist
  3. Update Permissions: Take effect immediately, only whitelisted users can send messages (if whitelist mode is enabled)
  4. Conversation Management: Automatically create related conversations for person channels

​
Clear Operation

When uids is an empty array:
  • Clear all whitelist entries for the channel
  • Restore normal permissions for all users
  • Disable whitelist mode

​
Whitelist Mechanism

​
Permission Features

Whitelisted users enjoy the following privileges:
PrivilegeDescriptionApplicable Condition
Send PermissionCan send messages to the channelWhen whitelist mode is enabled
Bypass RestrictionsBypass certain channel restrictionsBased on channel configuration
Priority ProcessingMessages may receive priority processingSystem configuration related
Conversation GuaranteeEnsure conversations are created normallyPerson channels

​
Whitelist Mode

  • When Enabled: Only whitelisted users can send messages
  • When Disabled: Whitelist does not affect message sending permissions
  • Person Channels: Whitelisted users automatically create conversations

​
Use Cases

​
Batch Management

# Set new whitelist, replacing all existing entries
curl -X POST "/channel/whitelist_set" -d '{
  "channel_id": "group123",
  "channel_type": 2,
  "uids": ["admin1", "admin2", "moderator1"]
}'

​
Clear Whitelist

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

​
Reset Whitelist

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

​
Comparison with Other Whitelist Operations

OperationFunctionUse Case
whitelist_addAdd users to existing whitelistIncrementally add privileged users
whitelist_setReplace entire whitelistBatch management, reset whitelist
whitelist_removeRemove specific users from whitelistRemove specific user privileges

​
Permission Hierarchy

Whitelist position in the permission system: 
System Users > Administrators > Blacklist > Whitelist > Regular Users

​
Conflict Handling

SituationResultDescription
Both in blacklist and whitelistTreated as blacklistBlacklist has higher priority
Only in whitelistEnjoy whitelist privilegesNormal whitelist user
Only in blacklistSubject to blacklist restrictionsNormal blacklist user
In neither listRegular user permissionsDefault permission handling

​
Best Practices

  1. Use Carefully: Set operation clears all existing whitelist, ensure this is intended behavior
  2. Backup Existing Data: Get current whitelist before setting as backup
  3. Permission Verification: Ensure operator has sufficient management permissions
  4. Progressive Management: For large channels, consider progressive whitelist management
  5. Monitor Effects: Monitor channel activity and user feedback after setting
  6. Document Records: Record whitelist change reasons and expected effects

​
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 whitelist failedClear operation failedCheck channel status and permissions
Add whitelist failedAdd operation failedCheck user ID validity