Roles

Note Make sure the bot has permission to manage your server’s roles.

This tutorial will walk you through some of the more advanced role management functions. In previous tutorials we made use of hasRole, giveRole, takeRole, but this tutorial will focus on creating, editing and deleting roles. It will showcase an example that gives your server admins the ability to allow certain users to create their own role and then freely change its name and color.

• Create
• Editing
• Deleting
• Example: Custom role for a member
  • allow-role
  • disallow-role
  • claim-role
  • edit-role
• Limitations

Create

In order to create a new role, you have to make use of the RoleInfo type. This type allows you to specify some information about the new role that you’re creating so that the bot can forward it to Discord.

Here are the available pieces of data that RoleInfo can accept:

.Name	String	required	The role’s name
.Color	Integer	optional	The color the role should have (as a decimal, not hex)
.Separate	Bool	optional	If true, members with this role show up separately on the side bar
.Permissions	Array[DiscordPermission]	optional	The overall permissions of the role
.Mentionable	Bool	optional	Whether this role is mentionable

It’s possible to create a new role by only supplying the name. This will result in a new role with all the settings set to default.

Once you’ve set up your RoleInfo data, you can pass it along to createRole. Here is an example:

// Create a role with default settings
{{$role := RoleInfo
    Name: "My Custom Role"
}}

{{$role = createRole $role}}
// Check if we got a valid role back
{{if $role}}
    {{respond (print "Created role: " $role.Name " " $role.ID)}}
{{else}}
    {{respond "Failed to create role :("}}
{{end}}

Here is another example, but this time we specify a color:

{{$role := RoleInfo
    Name: "My Custom Role"
    Color: (hexToInt "#ab65cf")
}}

{{$role = createRole $role}}

With this example it sets a couple of the permissions:

{{$role := RoleInfo
    Name: "My Custom Role"
    Permissions: (Array PermissionSendMessages PermissionSendMessagesInThreads)
}}

{{$role = createRole $role}}

Editing

For any role that the bot can manage, there are a few other functions that can edit these existing roles:

editRoleName roleID newName

This sets the role given by roleID to have newName. roleID is the Discord ID, not the role’s name.

editRoleColor roleID color

This sets the role given by roleID to have color which should be a decimal (not hex). roleID is the Discord ID, not the role’s name.

moveRoleAfter roleID afterID

moveRoleBefore roleID beforeID

These two move functions deal with the Discord role hierarchy. In Discord, roles that come after a certain role are higher up in the hierarchy, while roles that come before a certain role are lower down in the hierarchy. This can have a big impact on what permissions a role has: for example, trying to edit a role higher than your own highest role is not allowed.

The bot is able to shuffle roles around using moveRoleAfter and moveRoleBefore. The catch is that the bot is not allowed to move a role to a position higher than its own highest role. You will need to go into your guild’s settings and make sure the bot’s highest role sits somewhere in the role hierarchy such that allows it to do everything you need the bot to do.

Also keep in mind that roleID, afterID, and beforeID all need to reference the role IDs provided by Discord. They are not the role names.

Deleting

You can also delete a role using deleteRole roleID. For this function, roleID is still the Discord ID, not the role’s name.

Example: Custom role for a member

This example will create a few functions. The first two are functions that only your guild administrators can use, and they enable them to allow and disallow server members to create and manage their own role.

allow-role

/create-cmd name: allow-role description: Allow a certain user to create and manage their own role

Command initialization code

{{$option := CmdOption
    Type: OptionUser 
    Required: true
    Name: "user" 
    Description: "User to allow"
}}

{{addOptions $option}}

// Administrators only
{{setDefaultPermissions PermissionAdministrator}}

Command execute code

{{$user := (getInput "user").User}}
{{dbSet $user.ID "CustomRoleAllowed" true}}
{{respondPrivate (print $user.Username " can now create their own role")}}

disallow-role

/create-cmd name: disallow-role description: Disallows a user from having a custom role

Command initialization code

{{$option := CmdOption
    Type: OptionUser 
    Required: true
    Name: "user" 
    Description: "User to allow"
}}

{{addOptions $option}}

// Administrators only
{{setDefaultPermissions PermissionAdministrator}}

Command execution code

{{$user := (getInput "user").User}}
{{$allowed := dbGet $user.ID "CustomRoleAllowed"}}

{{if not $allowed}}
    {{respond "That user was not allowed to have a custom role"}}
    {{return}}
{{end}}

{{$role := dbGet $user.ID "CustomRoleID"}}

{{if $role}}
    {{$role = toInt64 $role.Value}}
    {{deleteRole $role}}
{{end}}

// Clear out database entries
{{dbDel $user.ID "CustomRoleAllowed"}}
{{dbDel $user.ID "CustomRoleID"}}

{{respond (print $user.Username " can no longer create a custom role.")}}

The next functions will be all about creating a custom role, editing its name, and editing its color.

claim-role

/create-cmd name: claim-role description: Claim a custom role in the server

Command initialization code

{{$option1 := CmdOption
    Type: OptionString 
    Required: true
    Name: "name" 
    Description: "Name of your custom role"
}}

{{$option2 := CmdOption
    Type: OptionInteger 
    Required: true
    Name: "color" 
    Description: "Color of your custom role as a decimal"
    MinValue: 0
    MaxValue: 16777215
}}

{{addOptions $option1 $option2}}

Command execution code

{{$user := context.Member.User}}
{{$allowed := dbGet $user.ID "CustomRoleAllowed"}}

{{if not $allowed}}
    {{respondPrivate "Sorry but you are not allowed to create a custom role."}}
    {{return}}
{{end}}

{{$roleID := dbGet $user.ID "CustomRoleID"}}

{{if $roleID}}
    {{$roleID = toInt64 $roleID.Value}}

    // Check if the role still exists
    {{if (getRole $roleID)}}
        {{giveRole $user.ID $roleID}}
        {{respondPrivate "You already have a custom role! Use role-edit to change it."}}
        {{return}}
    {{end}}
{{end}}

// Create a new role
{{$info := RoleInfo
    Name: (getInput "name").String
    Color: (getInput "color").Integer
}}

{{$role := createRole $info}}

// Make sure it worked
{{if not $role}}
    {{respond "Something went wrong. :( Try again later."}}
    {{return}}
{{end}}

{{respond (print "Created a custom role named " $info.Name)}}

// Update database and give user the new role
{{dbSet $user.ID "CustomRoleID" (toString $role.ID)}}
{{giveRole $user.ID $role.ID}}

edit-role

/create-cmd name: edit-role description: Edit your custom role

Command initialization code

{{$option1 := CmdOption
    Type: OptionString 
    Required: false
    Name: "name" 
    Description: "New name of your custom role"
}}

{{$option2 := CmdOption
    Type: OptionInteger 
    Required: false
    Name: "color" 
    Description: "New color of your custom role as a decimal"
    MinValue: 0
    MaxValue: 16777215
}}

{{addOptions $option1 $option2}}

Command execution code

{{$user := context.Member.User}}
{{$roleID := dbGet $user.ID "CustomRoleID"}}

{{if not $roleID}}
    {{respondPrivate "You do not have a custom role. Use `/claim-role` to make one."}}
    {{return}}
{{end}}

{{$roleID = toInt64 $roleID.Value}}

{{$name := getInput "name"}}
{{$color := getInput "color"}}

// Both name and color are optional inputs so we need to check
// to see if the user gave them to us
{{if $name}}
    {{editRoleName $roleID $name.String}}
{{end}}

{{if $color}}
    {{editRoleColor $roleID $color.Integer}}
{{end}}

{{respond "Finished editing your role!"}}

Limitations

Currently there is no way to set and manage a role image through the bot. This is a feature that is planned but may take some time to implement.