Everything about BedrockRelay

What it does

BedrockRelay connects a Minecraft server to one or more Discord channels. Chat, joins, leaves and deaths from Minecraft appear in Discord, and messages sent in Discord appear in Minecraft chat.

It has two parts. A small behaviour pack on your Minecraft server reports what happens in the world. The BedrockRelay service does everything else: it decides which channels hear what, formats the messages, and talks to Discord. You manage it all from the dashboard.

One Minecraft server can post to as many channels as you like, across as many Discord servers as you like. Each channel chooses what it hears.

What you need

• A Bedrock Dedicated Server. Either on your own machine or a VPS, or from a host that runs the official Bedrock server software. Realms and worlds hosted from a console or phone can't run it, because they don't allow the scripting features it needs.
• A Discord server where you have Manage Server permission, so you can add the bot.
• SFTP access to your Minecraft server, which your host's control panel gives you. It's the easiest route, and the installer does everything for you. If you only have a web file manager, you can download the pack and install it by hand instead.
• Beta APIs turned on for the world. The installer can do this for you. See why Beta APIs matter.

Why Beta APIs matter

Reading chat is still an experimental Minecraft feature, so it only works with the world's Beta APIs experiment on. Without it the pack loads, but it can't see what people say, so BedrockRelay won't install on a world without it.

Setting up

Open the dashboard, sign in with Discord, and choose Set up a Minecraft server. The setup shows one step at a time:

1. Add the bot to a Discord server. You approve it on Discord and come straight back. It only asks for the permissions it uses: View Channels, Send Messages, Embed Links and Manage Webhooks.
2. Name your Minecraft server. This is how it's labelled in Discord and on your dashboard.
3. Install the pack. Stop your Minecraft server, enter your SFTP details, and choose Connect and preview. You'll see exactly what will change before anything is written. Every file we change is backed up first, and other packs and their settings are left alone.
4. Start your Minecraft server. The page moves on by itself as soon as the pack connects.
5. Choose a channel. Chat starts flowing straight away.

Your SFTP details are used for that one connection and never stored by BedrockRelay. If you tick Remember these details on this device, your browser keeps the host, port, username and folder for that Minecraft server, so every later SFTP step fills them in and you only type the password. The password and SSH key are never remembered. Untick it to forget them.

Installing by hand

If you choose Download the pack instead, you get a zip that matches your Minecraft server's folder layout. Stop the Minecraft server and unzip it into the folder that holds server.properties, merging with what's there rather than replacing it. Then add the BedrockRelay entry from INSTALL.txt to your world's world_behavior_packs.json, keeping the entries already in it. Turn on Beta APIs and start the Minecraft server. The zip contains your Minecraft server's token, so keep it private.

Channels and events

Each connected channel has its own settings, which you can change on the Discord server's page in the dashboard.

Direction

Events

A common setup is #minecraft-chat with Chat both ways, plus a #server-log that's Minecraft → Discord only, with Join, Leave, Death and Connection notices.

You can also connect a channel with no events ticked. It then gets only the plugin posts you send to it, which suits a staff channel.

Shared chat

When a Minecraft server is connected to more than one channel (in two Discord servers, say), Shared chat also copies people's Discord messages between those channels, so everyone can talk to each other as well as to Minecraft. Every channel involved has to turn it on; it's off by default. Edits and deletions aren't copied.

When BedrockRelay can't use a channel

When you add BedrockRelay, Discord gives it a role called BedrockRelay with the permissions it asked for. That role applies across the whole Discord server, but each channel can override it. Private channels, and channels that take permissions away from @everyone or from certain roles, can take them away from BedrockRelay too.

In every channel it relays, BedrockRelay needs two permissions:

• View Channel, to see the channel and read what people say for Minecraft.
• Manage Webhooks, to post each message under the player's name and head.

The dashboard checks this for you. Channels BedrockRelay can't use are greyed out when you choose one, and a connected channel that later loses a permission shows a warning on its route.

To fix a channel:

1. In Discord, open the channel's settings (the cog next to its name) and choose Permissions.
2. Add the BedrockRelay role to the list of roles and members.
3. Set View Channel and Manage Webhooks to allowed (the green tick), and save.
4. Back in the dashboard, choose Check again.

If the channel takes its permissions from its category, you can make the same change on the category instead.

Connecting to another Discord server

Only the person who set up a Minecraft server can connect it to channels, in any Discord server. Add the bot to the other Discord server, open that Discord server's page in the dashboard, and add a channel. Anyone with Manage Server there can still disconnect it from their Discord server.

In Minecraft

• Discord messages appear as [Discord] Name: message, with the name in the colour of the person's highest Discord role.
• Discord bold, italic, underline, strikethrough and code are shown with Minecraft's own formatting.
• Chat that starts with ! stays in Minecraft and isn't sent to Discord, which is handy for other addons' chat commands.
• From Minecraft, @everyone, @here and role mentions are defused so they can't ping a whole Discord server.

Slash commands

Everything that configures BedrockRelay is on the dashboard. These five commands are for things you do from inside Discord, in a connected channel. Plugins can add more.

Commands from Discord

/relay run is off until you allow specific commands. Open your Minecraft server's page in the dashboard, find Commands from Discord, and add a rule for each command, such as weather, time or say.

• A rule set to Administrators only lets anyone with Discord's Administrator permission run it.
• A rule with a role also lets that role's members run it. Roles come from the Discord servers the Minecraft server is connected to.
• * allows every command, including op and stop. Only pair it with a role you trust completely.

Anything without a rule is refused. Only the Minecraft server's owner can change these rules.

Plugins

Plugins add Discord commands for your Minecraft world, such as /lastdeath to find where someone died, /world for the time and weather, or /top for leaderboards. Every plugin in the catalog has been reviewed.

1. In the dashboard, open Plugins and choose + Install beside the Minecraft server you want each plugin on. They collect in your list at the bottom of the page.
2. Choose Apply in the list. Everything for that Minecraft server installs over one SFTP connection, with a preview first, like the pack. Or download the files and add them yourself.
3. Restart the Minecraft server so it loads the plugin.
4. On that Minecraft server's page, switch the plugin on under Plugins. Its commands then appear in the Discord servers it's connected to.

• At first only Discord administrators can use a plugin. To let others use it too, add a role beside the plugin.
• Most answers are only shown to the person who asked, because they can reveal where people are or what they're carrying. A few, like /world and /top, are made to be shared and are shown to everyone in the channel.
• Commands that change something in your world ask "are you sure?" first.
• When a newer version is out, the Plugins page offers + Update, or Add all updates at once. + Remove takes a plugin off again. Updates and removals go in the same list.
• Plugins need pack v0.3.0 or newer, and the newest plugins need v0.4.0. The Plugins page says when a pack update is needed. Updating the pack never removes your plugins.
• Every plugin's code is public in the BedrockRelay plugins repository on GitHub, so you can read exactly what you're installing. Each plugin's Source link opens its code.
• Want to write your own? See the developer guide, then submit it to the repository.

Plugins that post by themselves

Some plugins post without being asked. Leaderboards, for example, announces when someone reaches 100 hours played. Once you switch one on, choose where its posts go under Posts to beside it. It posts nowhere until you do. Any channel connected to that Minecraft server can be chosen, including one with no events ticked, just for plugin posts.

Some plugins post several kinds of thing. Audit, for example, can post when someone places TNT, spawns a wither or mines diamonds. Those plugins list each kind under What it posts: untick any you don't want, and the rest still go to the channels you chose. If the pack is older than v0.4.2, the plugin posts every kind until it's updated.

Linking your account

Linking tells BedrockRelay which Minecraft player you are. Plugins can then answer about you without you typing your name: /lastdeath shows your own last death, and /top shows your rank.

1. Join the Minecraft server.
2. In a channel connected to it, run /relay link player: followed by your Minecraft name.
3. A 6-digit code appears in your Minecraft chat. Only you can see it.
4. Back in Discord, choose Enter code and type it in.

Codes work for 10 minutes. Run /relay link on its own to see your link or undo it. Links are separate for each Minecraft server, and the Minecraft server's owner can see and remove them on its page in the dashboard.

Your dashboard

• Overview has a card for each of your Minecraft servers showing who's online, today's messages, joins and deaths, and the last week's activity. Select a card to open that Minecraft server's page.
• A Minecraft server's page shows its status, a 30-day chart, every channel it's connected to across all your Discord servers, its command rules, and whether players can join it. When a newer pack is out, the Update pack button installs it the same way as the first time.
• A Discord server's page lists the Minecraft servers connected there, each channel's direction, events and shared chat, and the language the bot writes in there.

Languages

BedrockRelay speaks English, Deutsch, Español, Français, 日本語, Polski, Português (Brasil), Русский and 简体中文.

• The dashboard follows your browser's language. To change it, pick another from the language menu at the top of the page.
• What the bot writes in Discord is set per Discord server on its page in the dashboard, under Language in Discord. This covers joins, leaves, deaths, connection notices and the bot's answers to commands. Automatic follows the language in the Discord server's Community settings. Chat itself is never translated.
• Slash command descriptions appear in each member's own Discord language.

Most languages were machine translated to begin with, and the dashboard says so. They're improved by the people who use them: every language is a file in the BedrockRelay translations repository, where you can fix a mistake or add a language.

Removing and uninstalling

On your Minecraft server's page, choose Remove…. It's disconnected from every channel straight away, and its pack stops being accepted.

For 7 days you can bring it back from Recently removed on the Overview, with its channels, rules and statistics just as they were, and nothing to reinstall. After that it's deleted for good, including the webhooks the bot created in each channel. To delete it sooner, choose Delete forever next to Undo.

Taking the pack off your Minecraft server

In the same dialog, choose Also uninstall the pack over SFTP. You'll see a preview first, just like installing. It removes only what BedrockRelay added and backs up every file it edits. You can also turn Beta APIs back off for the world, but achievements stay disabled. To do it yourself:

1. Stop your Minecraft server.
2. Delete development_behavior_packs/BedrockRelay.
3. In worlds/<your world>/world_behavior_packs.json, delete the entry whose pack_id is 6f2a7c14-4b98-4e2a-9c31-2f7a5d0e11b4, and keep the rest.
4. In config/default/variables.json, delete the keys starting with relay_, and in config/default/secrets.json delete relay_token. If there's a config/c8e1d35a-90f7-4b6d-8a22-1d4b6e9f7c03 folder, delete it.
5. Start your Minecraft server.

Leave config/default/permissions.json alone, because other packs may rely on it.

Troubleshooting

Nothing appears in Discord

1. Check Beta APIs is on for the world your Minecraft server is actually running. This is the cause nine times out of ten.
2. Check the console when the Minecraft server starts. You should see [BedrockRelay] connected to https://bedrockrelay.com. If there's no [BedrockRelay] line at all, the pack didn't load. Make sure content-log-console-output-enabled=true is set in server.properties (some hosts set this in their control panel instead), then restart.
3. Check the channel's events. A channel without Chat won't show player chat.
4. Check the dashboard. If the Minecraft server shows as offline, the pack isn't reaching us. Try Reinstall pack on its page.

Setup is stuck on "Waiting for your Minecraft server to connect"

The page is waiting for the first check-in. Start or restart the Minecraft server, then work through the list above. You can also choose Skip for now and pick a channel; relaying starts as soon as the pack connects.

It's connected, but players can't join

The pack only needs to reach us, so a Minecraft server can be connected to BedrockRelay while players still can't get in. About once a minute, BedrockRelay checks it the way Minecraft does before joining, and your dashboard shows Can't join when that check fails:

• It answers with no server details. Minecraft treats that as offline. Turn on enable-lan-visibility in server.properties (on many hosts it's a setting in the control panel), then restart.
• Nothing answered. The port is closed to players, or players join at a different address. Check the Minecraft server's port (server-port) is open. If players use a different address, enter it under Where players join on the Minecraft server's page.

BedrockRelay checks the address your Minecraft server connects from, on the port in server.properties. Some hosts connect out from a different address than players join on; entering the join address fixes the check.

Discord messages don't appear in Minecraft

The channel needs a direction of Both ways or Discord → Minecraft, and the Chat event. Messages from other bots are ignored on purpose, so relays can't echo each other forever.

A channel is greyed out, or a route shows a warning

That channel's permissions stop BedrockRelay seeing it or posting in it. See When BedrockRelay can't use a channel for the two-minute fix.

/relay run says a command isn't allowed

Nothing runs until it's allowed. The Minecraft server's owner can add a rule under Commands from Discord.

Privacy and security

• SFTP details are used for one connection while you install or uninstall, then forgotten. They're never saved or logged.
• Tokens, the key the pack uses to identify your Minecraft server, are stored only in scrambled form, so they can't be read back, even by us. If your pack zip or its config files may have leaked, use Revoke all pack tokens under Security on the Minecraft server's page, then reinstall.
• Chat passes straight through and isn't kept. Messages waiting to reach your Minecraft server are held only until it collects them.
• Statistics are counts per day, such as messages, joins and deaths, not the messages themselves.
• Linked accounts store which Discord account goes with which Minecraft name on that Minecraft server, and nothing else. Anyone can undo their own link with /relay link.
• Only the person who set up a Minecraft server can connect it, change its channels, allow commands or remove it. Discord server managers can always disconnect it from their own Discord server.

The full details are in the Privacy Policy.