Skip to main content

​
Member Removal & Bans

The moderation system allows authorized members to remove (ban/kick) users from communities and manage the list of removed members.

​
Remove Members

Remove one or more members from a community. This can be a temporary or permanent ban, and optionally delete their recent messages. Method: communities.removeMembers Request: RemoveMembers
​
community_id
fixed64
Snowflake ID of the community
​
member_ids
fixed64[]
List of user IDs to remove from the community
​
until
fixed64
Unix timestamp indicating when the ban expires. If set to 0 or omitted, the ban is permanent.
​
delete_messages_since
fixed64
Unix timestamp indicating how far back to delete messages from the removed members. Messages sent after this timestamp will be deleted.
​
reason
string
Optional reason for the removal/ban. This can be displayed in audit logs or to the removed user.
Response: RemovedMembers
​
members
RemovedMember[]
List of members that were successfully removed

​
RemovedMember Structure

​
user_id
fixed64
Snowflake ID of the removed user
​
user
User
User object containing the user’s information
​
until
fixed64
Unix timestamp when the ban expires (if temporary). Null/0 for permanent bans.
​
reason
string
The reason provided for the removal
Example - Permanent Ban: 
RemoveMembers {
  community_id: 123456789
  member_ids: [987654321]
  reason: "Violation of community guidelines"
}
Example - Temporary Ban: 
RemoveMembers {
  community_id: 123456789
  member_ids: [987654321]
  until: 1735689600  # Unix timestamp for expiration
  reason: "Spamming (7 day ban)"
}
Example - Ban with Message Deletion: 
RemoveMembers {
  community_id: 123456789
  member_ids: [987654321]
  delete_messages_since: 1735603200  # Delete messages from last 24 hours
  reason: "Spam messages"
}

​
Get Removed Members

Retrieve the list of all banned/removed members in a community. Method: communities.getRemovedMembers Request: GetRemovedMembers
​
community_id
fixed64
Snowflake ID of the community
Response: RemovedMembers
​
members
RemovedMember[]
List of all removed/banned members, including their ban expiration times and reasons
This is useful for:
  • Displaying a ban list in moderation tools
  • Checking if a specific user is banned
  • Reviewing ban reasons and expiration times
  • Auditing moderation actions

​
Unban Members

Remove bans and allow previously removed members to rejoin the community. Method: communities.unbanMembers Request: UnbanMembers
​
community_id
fixed64
Snowflake ID of the community
​
member_ids
fixed64[]
List of user IDs to unban
Example: 
UnbanMembers {
  community_id: 123456789
  member_ids: [987654321, 111111111]
}
After unbanning, users can rejoin the community through an invite link or other join mechanism.

​
Permission Requirements

To use moderation actions, members must have the REMOVE_MEMBERS permission flag (value: 2048, or 1<<11). See Roles & Permissions for more details. Members with the ADMINISTRATOR permission can always perform moderation actions.

​
Ban Types

​
Permanent Ban

  • Set until to 0 or omit it
  • User cannot rejoin until manually unbanned
  • Use for serious violations

​
Temporary Ban

  • Set until to a future Unix timestamp
  • User automatically allowed to rejoin after expiration
  • Useful for cooling-off periods or minor infractions

​
Kick (Immediate Removal)

  • Remove user without adding to ban list
  • Currently implemented as a ban with immediate unban
  • User can rejoin immediately if they have an invite

​
Message Deletion

When removing members, you can optionally delete their recent messages using delete_messages_since:
  • Provide a Unix timestamp
  • All messages from the user sent after this timestamp will be deleted
  • Useful for removing spam or offensive content
  • Common options:
    • Last 24 hours: current_time - 86400
    • Last 7 days: current_time - 604800
    • Don’t delete messages: omit the field

​
Best Practices

  1. Always provide a reason - Helps with accountability and appeals
  2. Use temporary bans - For first-time or minor offenses
  3. Review removed members - Regularly check the ban list for expired bans
  4. Communicate clearly - Let users know why they were removed
  5. Document guidelines - Have clear community rules that justify removals

Build docs developers (and LLMs) love

Get started for freeTalk to us