Skip to main content

​
Chat Bridge

The Chat Bridge module synchronizes chat in both directions between your Minecraft server and a Discord channel. Messages sent in-game appear in Discord, and messages sent in Discord appear in-game — with player avatars, mention conversion, emoji translation, and typing indicators.

​
Overview

Chat Bridge links a single Discord channel to your server chat. When a player speaks in Minecraft, the message is forwarded to Discord; when a Discord user speaks, the message is relayed back to the server. With webhook mode enabled, Discord messages render using each player’s actual skin as the avatar.

​
Configuration

All keys live under features.chat-bridge in plugins/XDiscordUltimate/config.yml. 
features:
  chat-bridge:
    enabled: true
    chat-channel-id: "123456789012345678"
    chat-channel: "minecraft-chat"
    minecraft-to-discord: true
    discord-to-minecraft: true
    filter-bot-messages: true
    skin-provider: "crafthead"
    auto-create-webhook: true
    use-webhook: true
    webhook-url: ""
    minecraft-format: "**%player%**: %message%"
    discord-format: "&7[&9Discord&7] &b%user%&7: &f%message%"
    show-mentions: true
    play-mention-sound: true
    convert-emojis: true
    strip-discord-formatting: true
    show-player-prefix: true
    show-player-suffix: true
    discord-username-format: "%prefix%%player%"

​
Webhook vs Bot Mode

Chat Bridge can post Minecraft messages to Discord in two ways, controlled by use-webhook.

Webhook Mode (recommended)

Set use-webhook: true. Messages from Minecraft are posted through a Discord webhook, so each player appears as their own user with their Minecraft skin as the avatar. Enable auto-create-webhook: true and the plugin will create and manage the webhook for you, or supply a webhook-url manually.

Bot Mode

Set use-webhook: false. All Minecraft messages are posted by the bot account under a single name, with the format defined by minecraft-format. Simpler, but no per-player avatars.
Use webhook mode (use-webhook: true + auto-create-webhook: true) for the best experience. Players’ real Minecraft skins appear as their Discord avatars, and the bot manages the webhook lifecycle for you.

​
Skin Providers

The skin-provider key controls where player avatars are fetched from for webhook mode.
  • crafthead (default, recommended) — Most reliable provider. Works correctly with offline-mode (cracked) server names, not just premium accounts. Use this unless you have a specific reason not to.

​
Mention, Emoji & Typing Behavior

With show-mentions: true, the bridge translates mentions between formats. Discord @role and @user mentions are rendered as readable names in-game, and in-game mentions of Discord users are converted to proper Discord pings. Set play-mention-sound: true to play a sound in-game when a player is mentioned from Discord.
With convert-emojis: true, Discord shortcodes (e.g. :tada:) are converted to their unicode equivalent in Minecraft, and emoji in game chat are converted back to shortcodes in Discord. strip-discord-formatting removes Discord markdown (**bold**, __underline__, etc.) before relaying to Minecraft to keep in-game chat clean.
With show-typing-indicator: true, the bot emits a Discord typing indicator while a player is composing a message, so Discord users see that someone is about to speak.

​
Format Placeholders

Customize the message appearance with minecraft-format (how Discord messages appear in-game) and discord-format (legacy fallback for bot mode). The following placeholders are substituted:
PlaceholderReplaced with
%player%The Minecraft player’s username
%message%The chat message body
%user%The Discord user’s name
%prefix%The player’s LuckPerms prefix
%suffix%The player’s LuckPerms suffix
The discord-username-format key (%prefix%%player% by default) controls the webhook display name when show-player-prefix / show-player-suffix are enabled.

​
Next Steps

Account Verification

Link Discord accounts to Minecraft players with secure codes and brute-force protection.

Configuration

Reference for every module and key in config.yml.