Discord Integration

How to configure the UltraStaffChatPro Discord integration on your Minecraft server.

UltraStaffChatPro's Discord integration supports using a Discord Bot or a Discord Webhook. There are benefits and restrictions to each integration, however, we recommend the Discord Bot integration as it allows for two-way communication between Discord and your Minecraft server.

General configuration

You can customise how the {player} and {server} placeholders are replaced for messages sent from Discord. You can also change the "allowed mentions" for messages sent to Discord to prevent players in Minecraft from using "@everyone" or similar.

config.yml

  # Discord | Display
  display:
 
    # Display | Name
    #  How should Discord users display in-game?
    #  Options: "TAG" (Name#1234), "NAME" (Nickname), "USERNAME" (Username)
    name: "USERNAME"
 
    # Display | Server
    #  What should the {server} placeholder be
    #  replaced with for people talking from Discord?
    server: "Discord"
 
  # Discord | Allowed Mentions
  #  Options: "ALL" (@everyone, @here, users, roles), "ROLES" (users, roles), "USERS" (users), "NONE"
  allowed-mentions: "NONE"

Discord Bot

The Discord Bot integration allows two-way communication between staff members on your Minecraft server and in your Discord server. To set up the Discord Bot integration, you must create a Discord application and provide UltraStaffChatPro with the Bot token for your application.

1. Create Discord application

Start by creating a Discord application in the Discord Developer Portal. This application will be used by the Discord integration to connect to Discord. You can skip this step if you have already created an application you wish to use.

1. Open the Discord Developer Portal and log in to your Discord account.

2. Click on the "New Application" button at the top-right of the page.

3. Enter a name for your application and click "Create".

You should see a page similar to this image:

Discord Application page for example "UltraStaffChatPro" app

2. Reset bot token

Do not share the bot token with anyone, including Hypera staff members. Anyone with access to the bot token can authenticate with Discord as the bot, granting them access to any Discord server the bot is in. Hypera staff members will never ask you for your bot token. When providing your config.yml file in support tickets, we highly recommend redacting or removing the token.

After creating the Discord application, reset the Bot's token by following these steps:

1. Navigate to the application page in the Discord Developer Portal.

2. Click on "Bot" in the sidebar to view the bot settings.

3. Click "Reset Token" and then "Confirm" in the modal. You may have to re-authenticate with Discord to reset the token.

4. Click the "Copy" button to copy the generated token, then save it securely for later. The token can only be viewed once after being created. If you forget or lose access to the token, you must generate a new one.

Discord Bot page after resetting the token

What is a token?

A Discord token is similar to a password your Bot uses to authenticate with the Discord API and gateway. This allows the bot access to any Discord servers the bot is in, allowing messages to be sent and received by the bot.

3. Privileged Gateway Intents

This step is required for the Discord Bot integration to work correctly. Without the message content intent, the Discord bot will be unable to read the contents of messages sent on Discord, resulting in blank messages appearing in the staff-chat channels.

Once you have created a Discord application and reset the bot token, scroll down on the "Bot" page for your Discord application and enable the "Message Content Intent". This privileged gateway intent allows your Discord bot to receive the content of messages sent on Discord. Without this intent, the Discord bot will see empty messages.

Discord Bot message content intent enabled

Click "Save Changes" in the pop-up to save this change.

4. Add the Discord bot to your server

After you have created the Discord application, the Discord bot will not be any servers yet. You must add the Discord bot to your server in order for the Discord Bot integration to work.

You must have the "Manage Server" permission in the Discord server(s) to which you wish to add the bot.

Create an invite link for your Discord bot by following these steps:

1. Navigate to the application page in the Discord Developer Portal.

2. Click "OAuth2" in the sidebar and scroll down to the "OAuth2 URL Generator".

3. Select the bot scope under "Scopes".

   

   OAuth2 URL Generator with "bot" scope selected
4. Configure the bot permissions to your needs. It is recommended to restrict the permissions as much as possible, and only give the Discord bot permission to send and receive messages in the channel(s) for which you wish to use the Discord integration.

   

   OAuth2 URL Generator with "Send Messages", "Embed Links" and "Read Message History" permissions selected
5. Select "Guild Install" under "Integration type".

6. Copy the generated URL and open it in your browser.

   

   OAuth2 URL Generator with Generated URL and mouse clicking "Copy" button
7. Select the server you wish to add the Discord bot to and click "Authorise".

8. Once you have clicked "Authorise", you should see the bot in your server's member list.

Discord application authorisation page

5. Enable and configure the Discord Bot integration

Once you have created a Discord application, reset the bot token and added the Discord bot to your server, you are ready to configure UltraStaffChatPro to use the Discord bot! UltraStaffChatPro must also be provided with the ID of your Discord server and channel(s) from which you would like to send and receive messages. If you have Discord Developer Mode enabled, you can do this by right-clicking the server or channel and clicking "Copy ID".

Enable Discord Developer Mode

If you do not already have Discord's Developer Mode enabled:

1. Open the Discord app and click on the Settings button in the bottom-left of the screen.

2. Next, click on "Advanced" in the left sidebar in the Discord settings page.

3. Once you are on the Advanced page, enable the "Developer Mode" toggle to enable developer mode.

1. Start by enabling the Discord integration and setting the Discord integration mode to "BOT" in your config.yml file.

config.yml

# [ UltraStaffChatPro | Discord Configuration ]
discord:
 
  # Discord | Enabled
  enabled: true # <-- Make sure this is set to 'true'
 
  # Discord | Mode
  #  Options: "BOT", "WEBHOOK"
  mode: "BOT" # <-- Make sure this is set to "BOT"

1. Once you have enabled the Discord bot integration, you must provide the token you generated in step 2. If you have forgotten or lost your bot's token, you must reset the token again.

config.yml

  # Discord | Bot Configuration
  #  Only used if 'mode' is set to "BOT"
  bot:
 
    # Bot | Token
    token: "XXXX" # <-- Replace with your Discord bot token

1. Once you have configured the bot token, configure the Discord server and channel messages in the staff-chat should be sent to, and received from.

config.yml

    # Bot | Discord guild ID
    guild: "XXXX" # <-- Replace with the ID of your Discord server
 
    # Bot | Discord channel ID
    channel: "XXXX" # <-- Replace with the ID of the Discord channel for staff-chat

1. You can also customise your bot's status and activity.

config.yml

    # Bot | Status
    #  Options: "ONLINE", "IDLE", "DO_NOT_DISTURB", "INVISIBLE"
    status: "ONLINE"
 
    # Bot | Activity
    activity:
 
      # Activity | Enabled
      enabled: true
 
      # Activity | Type
      #  Options: "DEFAULT" (Playing), "WATCHING", "LISTENING"
      type: "WATCHING"
 
      # Activity | Message
      #  Placeholders: {online} (Total online players), {count} (Total online staff / People with the StaffList display permission)
      message: "{online} players on play.example.net"

1. You can customise each message sent to Discord in your messages.yml file. For each message sent to Discord, there is a separate message configuration where you can fine-tune each message to your liking:

messages.yml

    # Discord | StaffChat message format
    message:
      # Discord | Mode
      #  Options: "EMBED", "TEXT"
      mode: "EMBED"
 
      # Discord | Embed
      #  Only needed if 'mode' is set to "EMBED"
      embed:
        author:
          name: "{player}"
          url: ""
          image: "https://crafatar.com/avatars/{uuid}.png"
        title:
          text: ""
          url: ""
        description: "{message}"
        color: "#55FFFF"
        footer:
          text: "UltraStaffChatPro"
          icon: ""
        image: ""
        thumbnail: ""
        fields: {} # To use fields, remove '{}' here and uncomment the following lines.
#          1:
#            name: "Field 1"
#            value: "Test"
#            inline: true
#          2:
#            name: "Field 2"
#            value: "Test"
#            inline: true

      # Discord | Text
      #  Only needed if 'mode' is set to "TEXT"
      text: "**{player}**: {message}"

1. If you use UltraStaffChatPro's "multi-channel" feature, you can enable the Discord integration per channel, and configure each channel to use a different Discord Webhook URL. Multi-channels are configured in the config.yml file.

   config.yml

         # MultiChannel | Discord
         #  This is only used if the Discord integration is enabled.
         discord:
    
           # Discord | Enabled
           #  Should the Discord integration be used for this channel?
           enabled: true # <-- Set to 'true' to enable for this channel
    
           # Discord | Guild ID (Server ID)
           guild: "XXXXXXXXXXXXXXXXXX" # <-- Set to the Discord server ID for this channel
    
           # Discord | Channel ID
           channel: "XXXXXXXXXXXXXXXXXX" # <-- Set to the Discord channel ID for this channel

---

Discord Webhook

Discord Webhooks only allow one-way communication, by sending messages from Minecraft to Discord. Webhooks are unable to receive messages sent on Discord. If you want two-way communication, you must use the Discord Bot integration.

The Discord Webhook integration allows one-way communication between staff members on your Minecraft and Discord server. Messages can be sent to Discord from Minecraft, but not sent to Minecraft from Discord.

1. Create Discord Webhook

Do not share the Discord Webhook URL with anyone, including Hypera staff members. Anyone with access to the Discord Webhook URL can send messages to the channel. When providing your config.yml or messages.yml file in support tickets, we highly recommend redacting or removing all Discord Webhook URLs.

Start by creating a Discord Webhook for your staff-chat.

1. In the Discord app, locate the channel that you want messages to, then click the "Edit Channel" gear icon.

2. Once you have clicked "Edit Channel", click "Integrations" in the sidebar.

3. On the "Integrations" page, click the "Create Webhook" button to create a new webhook.

   

   Discord channel integration settings
4. Click on the created webhook, and click "Copy Webhook URL" to copy the URL.

   

   Created Discord webhook example
5. Optionally change the name or avatar of the created webhook. This will be overridden by the settings in UltraStaffChatPro, however it is recommended to label the webhook for easy identification later.

2. Enable and configure the Discord Webhook integration

Once you have created a Discord webhook, you can configure UltraStaffChatPro to use the Discord webhook integration!

1. Start by enabling the Discord integration and setting the Discord integration mode to WEBHOOK in your config.yml file.

config.yml

# [ UltraStaffChatPro | Discord Configuration ]
discord:
 
  # Discord | Enabled
  enabled: true # <-- Make sure this is set to 'true'
 
  # Discord | Mode
  #  Options: "BOT", "WEBHOOK"
  mode: "WEBHOOK" # <-- Make sure this is set to "WEBHOOK"

1. Once you have enabled the Discord webhook integration, you must provide a Discord Webhook URL for your staff-chat channel. This webhook URL will be used only for messages sent in the staff-chat, and not multi-channel (see step 5).

config.yml

    # Webhook | URL
    url: "https://discord.com/api/webhooks/XXXX/XXXX" # <-- Replace with the Discord Webhook URL for your staff-chat channel

1. You can customise the avatar and username for the Discord Webhook in the configuration file, and use placeholders to change the avatar and username for each player.

config.yml

  # Discord | Webhook Configuration
  #  Only needed if 'mode' is set to "WEBHOOK"
  #  Note: Two-way chat requires the use of a bot.
  webhook:
 
    # Webhook | Avatar
    #  Placeholders: {player}, {uuid}
    avatar: "https://crafatar.com/avatars/{uuid}.png"
 
    # Webhook | Username
    username: "{player}"

1. You can customise each message sent to Discord in your messages.yml file. For each message sent to Discord, there is a separate message configuration where you can fine-tune each message to your liking:

messages.yml

    # Discord | StaffChat message format
    message:
      # Discord | Mode
      #  Options: "EMBED", "TEXT"
      mode: "EMBED"
 
      # Discord | Embed
      #  Only needed if 'mode' is set to "EMBED"
      embed:
        author:
          name: "{player}"
          url: ""
          image: "https://crafatar.com/avatars/{uuid}.png"
        title:
          text: ""
          url: ""
        description: "{message}"
        color: "#55FFFF"
        footer:
          text: "UltraStaffChatPro"
          icon: ""
        image: ""
        thumbnail: ""
        fields: {} # To use fields, remove '{}' here and uncomment the following lines.
#          1:
#            name: "Field 1"
#            value: "Test"
#            inline: true
#          2:
#            name: "Field 2"
#            value: "Test"
#            inline: true

      # Discord | Text
      #  Only needed if 'mode' is set to "TEXT"
      text: "**{player}**: {message}"

1. If you use UltraStaffChatPro's "multi-channel" feature, you can enable the Discord integration per channel, and configure each channel to use a different Discord Webhook URL. Multi-channels are configured in the config.yml file.

config.yml

      # MultiChannel | Discord
      #  This is only used if the Discord integration is enabled.
      discord:
 
        # Discord | Enabled
        #  Should the Discord integration be used for this channel?
        enabled: true # <-- Set to 'true' to enable for this channel
 
        # Discord | Guild ID (Server ID)
        guild: "XXXXXXXXXXXXXXXXXX" # -- Ignored when using Webhook.
 
        # Discord | Channel ID
        channel: "XXXXXXXXXXXXXXXXXX" # -- Ignored when using Webhook.
 
        # Discord | Webhook configuration
        #  This is only used if the Discord integration is configured to use a webhook.
        webhook:
 
          # Webhook | Avatar
          #  Placeholders: {player}, {uuid}
          avatar: "https://crafatar.com/avatars/{uuid}.png"
 
          # Webhook | Username
          username: "{player}"
 
          # Webhook | URL
          url: "https://discord.com/api/webhooks/XXXXXXXXXXXXXXXXXX/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"