Learn how to build a Discord community linked to external services by using Discord’s “Linked Roles” feature.
In this article, we will explain how to develop an app that links external service accounts such as Steam and YouTube with Discord accounts and automatically assigns roles to users who meet specific conditions, in a way that is easy for beginner engineers to understand.
Development Flow
Preparation in the Discord Developer Portal
- Create a new application from the Discord Developer Portal.
- Create a Bot user in the “Bot” tab of the application.
- In the “OAuth2” tab, use the OAuth2 URL Generator, select the required scopes such as identify and connections, and set the redirect URL.
- The redirect URL is the URL to which the user is redirected after authentication (e.g., http://localhost:3000/callback).
Implementing the OAuth2 Authentication Flow
- When a user attempts to connect to an external service within the Discord app, your app redirects the user to the OAuth2 authentication URL.
- The user logs in to the external service and grants access to the app.
- The external service redirects the user with the authentication code to the pre-configured redirect URL.
- The app uses this authentication code to obtain an access token.
Integrating with External Service APIs
- Refer to the API documentation of the external service you want to integrate with, such as Steam and YouTube, and check how to obtain the necessary information.
- Send API requests using the access token to obtain user information (e.g., Steam ID, YouTube channel subscription status, etc.).
Setting Linked Roles Metadata
- Set the metadata for the linked roles using the Discord API’s PUT /applications/{application.id}/role-connections/metadata endpoint.
- The metadata includes the key that represents the condition for assigning the role and a description (name, description) corresponding to that key.
- For example, you can set the condition “owns a specific game” with the key has_game.
- Use a Bot token for this API request.
Setting Roles on the Discord Server
- Create a new role on the Discord server.
- Go to the “Roles” > “Linked” tab in the server settings.
- Select the linked role you created, and set the requirements for obtaining the role (the key and value set in the metadata).
- For example, you can set the role to be assigned if the has_game key is true.
Connections by Users and Role Assignment
- Within the Discord server, users select the server name, then select “Apps” > your integration app name > the service they would like to link and connect their external service account.
- Based on the information obtained from the external service API and the metadata of the linked role, the app assigns roles to users.
Frequently Asked Questions (FAQ)
Q: Why is OAuth2 used?
A: OAuth2 is a standard authentication framework for allowing users to securely grant access to external services without sharing their passwords.
Q: What is the redirect URL for?
A: The redirect URL is the location where the user is redirected after authentication. The external service redirects to this URL with an authentication code. Your app uses this code to get an access token.
Q: What is the difference between a Bot token and a user token?
A: A Bot token is used to authenticate a Bot user (app). A user token is used to authenticate individual users. A Bot token is used to set linked roles metadata for security reasons.
Q: Can I integrate with multiple external services?
A: Yes, you can integrate with multiple external services. You need to implement the OAuth2 flow and API integration for each service.
Q: What conditions can I use to grant roles?
A: You can set various conditions based on the information that can be obtained from the external service API. For example, ownership of a specific game, subscription to a specific channel, or achievement of a specific score.
Q: What happens to roles if a user disconnects?
A: Your app needs to detect disconnections and implement a process to remove the roles as needed.
Q: What programming languages and libraries can be used for development?
A: You can use virtually any language that can send HTTP requests. Node.js, Python, and Go are commonly used. Using Discord API wrapper libraries such as Discord.js and discord.py will make development easier.
Additional Notes
- Error Handling: It is important to implement proper error handling for API request errors and authentication flow errors.
- Security: Keep in mind security during development, such as managing Bot tokens and implementing the OAuth2 flow correctly.
We hope this article will be helpful in developing your app.