Linked Roles

How to use Linked Roles in Carbon to create roles that users can claim based on specific criteria, including setup and deployment instructions.

Linked Roles are a handy feature of Discord that allows you to create roles that users have to meet certain criteria in order to claim those roles.

Admin Standpoint

Read more about Linked Roles from an admin standpoint.

User Standpoint

Read more about Linked Roles from a user standpoint.

Usage

Linked Roles are straightforward to use in Carbon, simplify create an instance and pass it to the plugins array in your createHandle function factory.

You can only have five metadata per application, and they apply across all guilds your app is in.

To add Linked Roles to your bot, you'll need to create a new instance of the LinkedRoles class and pass it your client and some metadata. The metadata is an array of objects that define the criteria for each role. In this example, we're creating a role that can only be claimed by users who have the is_staff metadata set to true.

src/index.ts

import { createHandle, Client, ApplicationRoleConnectionMetadataType } from "@buape/carbon"
import { LinkedRoles } from "@buape/carbon/linked-roles"
 
const handle = createHandle((env) => {
    const client = new Client({
        // Add these options and environment variables
        baseUrl: String(env.BASE_URL),
        clientSecret: String(env.CLIENT_SECRET),
    }, [ ... ])
    const linkedRoles = new LinkedRoles(client, {
        metadata: [
            {
                key: 'is_staff',
                name: 'Verified Staff',
                description: 'Whether the user is a verified staff member',
                type: ApplicationRoleConnectionMetadataType.BooleanEqual
            }
        ],
	    metadataCheckers: {
		    is_staff: async (userId) => {
                const allStaff = ["439223656200273932"]
                return allStaff.includes(userId)
		    }
	    }
    })
    return [client, linkedRoles]
})

Configure Portal URLs

Just like with interactions, you'll need to configure some URLs in your Discord Developer Portal to handle Linked Roles. Firstly, set "Linked Roles Verification URL" to <BASE_URL>/linked-roles/verify-user and add a OAuth2 redirect URL of <BASE_URL>/linked-roles/verify-user/callback.

Deploy Your Metadata to Discord

Finally, to deploy your linked roles metadata to Discord, navigate to <BASE_URL>/linked-roles/deploy?secret=<DEPLOY_SECRET> in your browser. This will send your metadata to Discord, where it will be used to create the roles.

Admin Standpoint

User Standpoint

Usage

Add a Linked Roles Instance

Configure Portal URLs

Deploy Your Metadata to Discord

On this page