Temporary Roles: Grant Roles for a Time and Remove Them Automatically

With temporary roles you grant a role for a certain time, for example 7 days as an event participant or 2 hours of access to a channel. When the time runs out, Kage removes the role automatically. You control it through commands or in the dashboard.

For a short walkthrough, see the guide Temporary roles.

Requirements

• Permissions: The /temprole commands can only be used with the Manage Roles permission. In the dashboard you need Manage Server (or access granted for this module).
• Kage's permissions: Kage needs Manage Roles, and its role must be above the role to be granted in the role list.
• Is Kage running? The expiry check works inside the bot. If it is offline at the time of expiry, it catches up on the removal as soon as it runs again.

Commands

Only you see all replies.

The duration

The duration consists of a whole number and a unit: m minutes, h hours, d days or w weeks, for example 30m, 2h, 7d or 1w. Kage does not recognize other notations such as "1 day" or "90 minutes and 5 seconds" and rejects them with a notice.

How it works

1. Granting: /temprole grant gives the role immediately and stores person, role, expiry time, reason and the granting person. If granting fails (for example because of the role order), Kage reports it and nothing is stored.
2. Checking: Kage checks every minute which time limits have expired.
3. Removing: When a limit has expired, Kage removes the role and notes it in the module's Logs tab ("Temporary role … removed (expired)").
4. Cleaning up: Kage then deletes the entry.

Extending and granting more than once

If you grant the same role to the same person again, Kage creates another entry. As long as another, not yet expired entry exists, the role stays when one entry expires: it only disappears when the latest entry expires.

Revoking early

/temprole revoke deletes the entry and removes the role immediately if the person still holds it. If Kage finds no entry, it reports that without changing anything.

If the person is gone

If the person has left the server, or the role no longer exists, Kage just deletes the entry.

If Kage cannot remove the role

If Kage lacks the permission on expiry or its role sits too low, it writes a warning to the operating log and deletes the entry anyway. The role then stays with the person until you remove it by hand. In that case, check the role order.

In the dashboard

Under Temporary roles, you grant a role by searching for a member, the role, the duration and an optional reason. Below, the dashboard lists the active temporary roles with person, role, expiry and reason. With Revoke you take a role back early.

Interplay with Role Panels

Role Panels can also grant roles for a limited time (field "temp. hrs"). Kage uses the same time-limit management for this: the entries appear in the list of active temporary roles. If someone removes the role at the panel early themselves, Kage deletes the time limit.

Settings at a glance

Temporary roles have no settings of their own. There are only the commands and the dashboard page.

Checking the result

1. Grant: /temprole grant with a test account, a test role and 2m.
2. List: /temprole list shows the role with its expiry time.
3. Wait: After about 3 minutes at most, the role is gone, and the Logs tab names the removal.
4. Early: Grant again and remove with /temprole revoke.

Troubleshooting

"Invalid duration"

Use a whole number with the unit m, h, d or w, for example 2h. Spaces between number and unit are allowed; decimals and several units are not.

The role cannot be granted

Kage sits below the role in the role list, or it lacks Manage Roles. Kage reports the missing permission in the reply.

The role stays after expiry

Kage could not remove it (role order or permission), or a further, later entry for the same role and person still exists. Check /temprole list.

The time limit is too short or too long

The limit starts at granting. If you grant again, the latest limit applies.

Further reading

Roles by button or dropdown: Role Panels. Roles on join: Auto roles.