Rate Limits

Shield comes with the ability to rate limit users who exceed thresholds for specified events. This guide serves to explain what they are, how they work, and how to set them up.

Audit Logs

Discord provides a feature known as audit logs, an immutable record of server actions taken. Shield hooks into this feature, listening for new log entries. These audit logs contain both the type of event that occurred (the full list of which can be found in Discord's documentation (opens in a new tab)) as well as the user who initiated the event.

Storing Member Data

When Shield receives an audit log entry, it goes through a multi-step process. These are as follows:

• It first checks to see whether there is an active rate limit for the event type. If not, it does nothing.
• If there is an active rate limit, Shield will log this event to its database.
• If Shield detects that the user has more than the maximum number of events allowed in the timeframe, it takes action against that user. The action taken is specified by the action parameter, which can take one of four values.
  • If action is warn, then Shield will send a DM to the user, warning them that they have exceeded the rate limit.
  • If action is remove_roles, then Shield will remove all roles from that user (that it is able to).
  • If action is kick, then Shield will kick the user from the server.
  • If action is ban, then Shield will ban the user from the server.
• After timeframe seconds has passed, the user is reset to 0 actions.

With this implementation, the user is able to execute limit event of type event_id in timeframe seconds.

Example

Imagine there is a rate limit in place with the following parameters

• The event ID is set to 25 — i.e. a member role update
• The limit is set to 2
• The timeframe is set to 180
• The action is set to remove roles

Under this setup, users are limited to 2 role updates every 3 minutes. If a user tries executing a third role update before the 3 minutes are up, Shield would remove all of that user's roles.