Skip to main content

Add Role Member

Assigns a role to a Discord server member.

Common Properties​

  • Name - The custom name of the node.
  • Color - The custom color of the node.
  • Delay Before (sec) - Waits in seconds before executing the node.
  • Delay After (sec) - Waits in seconds after executing node.
  • Continue On Error - Automation will continue regardless of any error. The default value is false.
info

If the ContinueOnError property is true, no error is caught when the project is executed, even if a Catch node is used.

Inputs​

  • Client Id - The Discord bot client identifier from the Connect node (optional if Bot Token provided).
  • Server Id - The Discord server (guild) ID where the role assignment will occur.
  • User Id - The ID of the Discord user to assign the role to.
  • Role Id - The ID of the role to assign.

Options​

  • Bot Token - Discord bot token credential (optional if using Client ID from Connect node).

How It Works​

The Add Role Member node assigns a role to a server member. When executed, the node:

  1. Authenticates using either Client ID or direct bot token
  2. Validates the server ID, user ID, and role ID
  3. Sends a role assignment request to Discord API
  4. Adds the role to the specified user

Requirements​

  • Active Discord bot session (Client ID) or bot token credentials
  • Valid server ID, user ID, and role ID
  • Manage Roles permission in the server
  • Bot's highest role must be higher than the role being assigned
  • The user must be a member of the server

Error Handling​

The node will return specific errors in the following cases:

  • ErrInvalidArg - Client ID or bot token missing/invalid
  • ErrInvalidArg - Server ID is empty
  • ErrInvalidArg - User ID is empty
  • ErrInvalidArg - Role ID is empty
  • Discord API errors (missing permissions, role hierarchy issues, user not in server, etc.)

Example: Assign Verified Role​

Inputs:

  • Server Id: "123456789012345678"
  • User Id: "987654321098765432"
  • Role Id: "555555555555555555"

Result: User receives the specified role.

Example: Auto-Role on Command​

Flow:

1. Interaction In (command: /verify) → interaction
2. Verify user (custom logic)
3. If verified:
   - Add Role Member
     - Server Id: {{interaction.GuildID}}
     - User Id: {{interaction.Member.User.ID}}
     - Role Id: "555555555555555555"
   - Interaction Out: "You've been verified!"

Result: User gets verified role after running command.

Example: Welcome Role Assignment​

Flow:

1. Receive Message (new member join event via custom trigger)
2. Add Role Member
   - Server Id: {{server_id}}
   - User Id: {{new_member.id}}
   - Role Id: "666666666666666666" (Welcome role)
3. Send Direct Message to user
   - Message: "Welcome! You've been given the Welcome role."

Result: New members automatically get a welcome role.

Example: Achievement System​

Flow:

1. User completes task
2. Check achievement requirements
3. If requirements met:
   - Add Role Member
     - Role Id: {{achievement_role_id}}
   - Send Channel Message
     - Message: "Congratulations {{user}}! You earned the {{role_name}} role!"

Result: Users earn roles as achievements.

Getting Role IDs​

  1. Enable Developer Mode in Discord (User Settings > Advanced)
  2. Right-click on a role in Server Settings > Roles
  3. Select "Copy ID"

Role Hierarchy​

Discord's role hierarchy rules:

  • Bots can only assign roles lower than their highest role
  • The bot's highest role must be above the role being assigned
  • Server owner can assign any role
  • Users with Manage Roles permission still subject to hierarchy

Example hierarchy (top to bottom):

  1. Admin (bot cannot assign)
  2. Bot Role (bot's highest role)
  3. Moderator (bot CAN assign)
  4. Member (bot CAN assign)

Use Cases​

  • Verification systems - Assign verified role after verification
  • Auto-roles - Assign roles to new members
  • Achievement systems - Award roles for accomplishments
  • Access control - Grant access to channels via roles
  • Event participation - Assign event participant roles
  • Level systems - Assign roles based on user levels
  • Subscription tiers - Assign premium/supporter roles

Bot Permissions Required​

  • Manage Roles - Required to assign roles
  • Bot's role must be higher in hierarchy than the role being assigned

Role Assignment Behavior​

When a role is assigned:

  • User immediately receives the role's permissions
  • Role appears in the user's role list
  • User gets access to role-restricted channels
  • Role color may change the user's name color (if role is hoisted and colored)
  • Audit log records the role assignment

Multiple Roles​

To assign multiple roles to a user:

1. Add Role Member (Role 1)
2. Add Role Member (Role 2)
3. Add Role Member (Role 3)

Conditional Role Assignment​

Flow:

1. Get user activity data
2. Condition: activity > 100
3. If True:
   - Add Role Member (Active Member role)
4. Condition: activity > 1000
5. If True:
   - Add Role Member (Super Active role)

Tips and Best Practices​

  • Verify hierarchy - Ensure bot's role is high enough
  • Check permissions - Verify Manage Roles permission
  • User validation - Confirm user is in the server
  • Error handling - Handle cases where role assignment fails
  • Logging - Log role assignments for audit purposes
  • Automation - Use role assignment for automated workflows
  • Testing - Test role assignments in a development server first
  • Role limits - Be aware users can have up to 250 roles