Skip to content

Discord Integration Configuration

See also: Discord Verification Frontend Implementation for the frontend verification flow.

Overview

The LBS Foundry platform integrates with Discord to provide community engagement and user verification features. This document outlines the configuration requirements and setup process for the Discord integration.

Required Configuration Keys

The Discord integration requires the following configuration keys to be set in your appsettings.json or environment variables:

Core Discord Settings

Configuration Key Description Example Value Required
Discord:BotToken Discord bot authentication token YOUR_DISCORD_BOT_TOKEN Yes
Discord:ApplicationId Discord application ID YOUR_DISCORD_APPLICATION_ID Yes
Discord:PublicKey Discord application public key YOUR_DISCORD_PUBLIC_KEY Yes
Discord:VerifiedRoleName Name of the role to assign verified users Verified Yes
Discord:VerificationChannelName Name of the channel for verification instructions verification Yes
Discord:LogLevel Logging level for Discord operations Information No (defaults to Information)

Verification Settings

Configuration Key Description Example Value Required
Discord:Verification:HmacSecret Secret key for HMAC token generation YOUR_HMAC_SECRET_KEY Yes
Discord:Verification:BaseUrl Base URL for verification links https://ballr.lbs.com Yes
Discord:Verification:TokenExpiryMinutes Token expiration time in minutes 60 No (defaults to 60)

Configuration Example

appsettings.json

{
  "Discord": {
    "BotToken": "YOUR_DISCORD_BOT_TOKEN",
    "ApplicationId": "YOUR_DISCORD_APPLICATION_ID",
    "PublicKey": "YOUR_DISCORD_PUBLIC_KEY",
    "VerifiedRoleName": "Verified",
    "VerificationChannelName": "verification",
    "LogLevel": "Information",
    "Verification": {
      "HmacSecret": "YOUR_HMAC_SECRET_KEY_FOR_DISCORD_VERIFICATION",
      "BaseUrl": "https://ballr.lbs.com",
      "TokenExpiryMinutes": 60
    }
  }
}

Environment Variables

For production environments, use environment variables instead of storing sensitive values in configuration files:

# Core Discord Settings
Discord__BotToken=YOUR_DISCORD_BOT_TOKEN
Discord__ApplicationId=YOUR_DISCORD_APPLICATION_ID
Discord__PublicKey=YOUR_DISCORD_PUBLIC_KEY
Discord__VerifiedRoleName=Verified
Discord__VerificationChannelName=verification

# Verification Settings
Discord__Verification__HmacSecret=YOUR_HMAC_SECRET_KEY
Discord__Verification__BaseUrl=https://ballr.lbs.com
Discord__Verification__TokenExpiryMinutes=60

Discord Server Setup

Required Discord Server Configuration

  1. Create Verification Role
  2. Create a role with the name specified in Discord:VerifiedRoleName (default: "Verified")
  3. Configure role permissions as needed for verified users

  4. Ensure the bot's role is higher in the hierarchy than the verified role

  5. Create Verification Channel

  6. Create a text channel with the name specified in Discord:VerificationChannelName (default: "verification")
  7. Set channel permissions so all users can view but only the bot can send messages

  8. The bot will automatically post verification instructions in this channel

  9. Bot Permissions The Discord bot requires the following permissions:

  10. Manage Roles: To assign/remove the verified role
  11. Read Messages/View Channels: To read commands
  12. Send Messages: To respond to users
  13. Use Slash Commands: To register and handle slash commands
  14. Manage Messages: To manage verification channel messages

Discord Bot Setup

  1. Create Discord Application
  2. Go to https://discord.com/developers/applications
  3. Click "New Application" and give it a name
  4. Navigate to the "Bot" section
  5. Click "Add Bot"

  6. Copy the bot token for Discord:BotToken

  7. Configure Bot Settings

  8. Enable "Server Members Intent" for role management

  9. Disable "Public Bot" if you only want to invite it to specific servers

  10. Get Application Credentials

  11. In "General Information", copy:

    • Application ID for Discord:ApplicationId
    • Public Key for Discord:PublicKey

  12. Invite Bot to Server

  13. In "OAuth2 > URL Generator"
  14. Select scopes: bot, applications.commands
  15. Select permissions mentioned above
  16. Use the generated URL to invite the bot to your server

Verification Flow

  1. User Initiates Verification
  2. User types /verify in any Discord channel
  3. Bot generates a unique verification token

  4. Bot sends a private message with verification link

  5. Web Verification

  6. User clicks the verification link
  7. Link redirects to the ballr website

  8. User completes authentication on the website

  9. Verification Completion

  10. Website calls the verification endpoint with the token
  11. System links Discord account to ballr account
  12. Bot assigns the verified role to the user
  13. User gains access to verified-only channels

Troubleshooting

Common Issues

  1. Bot Not Responding to Commands
  2. Ensure bot token is correct
  3. Check bot is online in Discord

  4. Verify bot has permission to read messages in the channel

  5. Role Not Being Assigned

  6. Verify role name matches configuration
  7. Ensure bot role is higher than verified role in hierarchy

  8. Check bot has "Manage Roles" permission

  9. Verification Link Not Working

  10. Confirm BaseUrl is correct and accessible
  11. Check HMAC secret matches between Discord bot and web API
  12. Verify token hasn't expired (default 60 minutes)

Logging

Enable debug logging for detailed troubleshooting:

{
  "Discord": {
    "LogLevel": "Debug"
  },
  "Logging": {
    "LogLevel": {
      "LBS.Core.Integration.Discord": "Debug"
    }
  }
}

Security Considerations

  1. Never commit sensitive values to source control
  2. Use environment variables for production deployments
  3. Rotate HMAC secret regularly
  4. Monitor verification logs for suspicious activity
  5. Limit bot permissions to only what's necessary
  6. Use HTTPS for all verification URLs