Discord Integration (discord.yml)

Discord Integration Configuration

This documentation explains how to configure the Discord integration for Jails+. The Discord integration allows server administrators to send jail-related notifications to a Discord channel.

Configuration Overview

The Discord integration is configured through the discord.yml file in your Jails+ plugin folder.

Enabling Discord Integration

enabled: true

Set this value to true to enable Discord integration or false to disable it completely.

Bot Settings

bot:
  token: "BOT-TOKEN-HERE"
  name: "Jails+ Punishments"

token: Your Discord bot token. You can obtain this from the Discord Developer Portal.
name: The name of your bot that will appear in embed footers and messages.

Channel Configuration

channel:
  announce-channel: "1234567890"

announce-channel: The ID of the Discord channel where jail notifications will be sent. You can obtain this by right-clicking on a channel in Discord and selecting "Copy ID" (Developer Mode must be enabled in Discord settings).

Message Settings

messages:
  announce-jails: true
  announce-unjails: true
  use-embeds: true
  player-heads: true
  send-startup-message: true
  send-shutdown-message: true

announce-jails: When set to true, notifications will be sent when a player is jailed (includes regular jails, temporary jails, and IP-jails).
announce-unjails: When set to true, notifications will be sent when a player is released from jail.
use-embeds: When set to true, messages will be sent as rich Discord embeds. When set to false, plain text messages will be used instead.
player-heads: When set to true, player head avatars will be displayed in embeds as thumbnails.
send-startup-message: When set to true, a message will be sent when the plugin/server starts up.
send-shutdown-message: When set to true, a message will be sent when the plugin/server shuts down.

Plain Text Message Formats

plain-format:
  # Available placeholders: {player}, {jails}, {duration}, {reason}, {jailer}, {time}, {date}, {name}, {version}
  jail: "**{player}** has been jailed in **{jails}** for **{duration}** | Reason: {reason} | By: {jailer}"
  unjail: "**{player}** has been released from **{jails}** | Reason: {reason} | By: {unjailer}"
  ipjail: "**{player}** has been IP-jailed for **{duration}** by **{jailer}** | Reason: {reason}"

These formats determine how plain text messages look when use-embeds is set to false. You can customize the messages using the available placeholders.

Embed Configuration

Embeds are rich message formats that look more appealing in Discord. You can customize different types of embeds:

Jail/IP-Jail Event Embed

embeds:
  jail:
    title: "Player Jailed"
    description: "**{player}** has been jailed in `{jails}` for `{duration}`\n\nReason: {reason}"
    ipjail-description: "**{player}** has been ip-jailed in `{jails}` for `{duration}`\n\nReason: {reason}"
    color: "FF0000"
    thumbnail: "{player_head}"
    timestamp: true
    footer:
      text: "{name}"
    fields:
      - "Player|`{player}`|true"
      - "Jail|`{jails}`|true"
      - "Duration|`{duration}`|true"
      - "Jailed By|`{jailer}`|true"
      - "Date|`{date}`|true"
      - "Status|`{status}`|true"

Unjail Event Embed

unjail:
  title: "Player Unjailed"
  description: "**{player}** has been **released** from `{jails}`\n\nReason: {reason}"
  color: "00FF00"
  thumbnail: "{player_head}"
  timestamp: true
  footer:
    text: "{name}"
  fields:
    - "Player|`{player}`|true"
    - "Released From|`{jails}`|true"
    - "Unjailed By|`{unjailer}`|true"
    - "Date|`{date}`|true"
    - "Status|`FREE`|true"

Startup and Shutdown Embeds

startup:
  title: "Connected"
  description: "**{name}** is now up and running!"
  color: "00FF64"
  timestamp: true
  footer:
    text: "{name} v{version}"
  fields:
    - "Status|`ONLINE`|true"
    - "Version|`v{version}`|true"

shutdown:
  title: "Disconnected"
  description: "**{name}** is going **OFFLINE**..."
  color: "FF3232"
  timestamp: true
  footer:
    text: "{name} v{version}"
  fields:
    - "Status|`OFFLINE`|true"

Embed Components Explained

title: The title of the embed
description: The main text content of the embed
color: Hexadecimal color code (without the #) for the left border of the embed
thumbnail: URL or placeholder for an image to display in the corner of the embed
timestamp: When set to true, includes a timestamp in the embed
footer: Configures text and optional icon that appears at the bottom of the embed
fields: List of fields to display in the embed in format "Name|Value|Inline" where Inline is a boolean that determines if fields are displayed side by side

Error Handling Configuration

error-handling:
  retry-attempts: 3
  retry-delay: 5
  log-errors: true

retry-attempts: Number of times the plugin will attempt to resend a message if it fails to send.
retry-delay: The delay in seconds between retry attempts.
log-errors: When set to true, errors encountered when sending messages will be logged to the console.

Available Placeholders

The following placeholders can be used in both plain text messages and embeds:

{player} - Name of the player being jailed/unjailed
{jails} - Name of the jail
{duration} - Duration of the jail sentence
{reason} - Reason for the jail/unjail
{jailer} - Name of the player or entity who jailed the player
{unjailer} - Name of the player or entity who unjailed the player
{date} - Current date and time
{status} - Status of the player (JAILED, IP-JAILED, FREE, etc.)
{name} - Name of the Discord bot (from bot.name setting)
{version} - Version of the Jails+ plugin
{player_head} - URL to the player's head avatar (only works in embeds)

Setup Instructions

Create a Discord bot through the Discord Developer Portal
Generate a bot token and add it to the configuration
Invite the bot to your server with appropriate permissions
Enable Developer Mode in Discord settings
Right-click on the channel where you want notifications and copy the ID
Add the channel ID to the configuration
Configure the message formats and other settings as desired
Restart your server or reload the plugin

PreviousMain Configuration (config.yml)NextLanguages and Messages

Last updated 1 month ago