Skip to content

Discord integration

BeamJoy posts to Discord by itself. There is no companion bot and no second plugin: you give it a webhook URL per channel, tick what that channel should receive, and it posts.

It does nothing until a webhook exists. A fresh install has none, which is why nothing appears in your server until you add one.

Config → General → Discord, which needs SetConfig — admin by default.

In Discord, on the channel you want posts in: Edit channel → Integrations → Webhooks, create one, and copy its URL. In BeamJoy, Add webhook, give it a name you will recognise — Race results, Staff — paste the URL, and tick what it carries.

Send test post puts a message in the channel so you know it works before you wait for a race to end. It is only offered once your changes are saved.

A server can hold up to ten webhooks, each with its own selection, which is the point: a results channel and a moderation channel need very different things.

Post New webhook What it is
Race results On A solo run posts the time, the leaderboard place and the vehicle. A race with several players posts the full standings when it ends.
Only personal bests and records Off Narrows the above: skip runs that beat nobody’s personal best.
Map and kick votes On Started, passed, failed, cancelled.
Players joining and leaving Off One line each.
Player chat Off Every public chat message, under the player’s own name.
Deliveries Off Completed delivery and convoy jobs.
Hunter rounds Off Results.
Infected rounds Off Results.
Derbies Off Results.
Bus lines Off Completed runs.

Those are the defaults a new webhook gets. Posts added to BeamJoy after you made a webhook default to off for it, so an update never starts your results channel carrying chat.

Anyone holding a webhook URL can post to that channel as your server, forever, without being in your Discord. BeamJoy treats them accordingly:

  • They are only ever sent to players who hold the config permission. Nobody else’s game has them, even in memory.
  • The field is masked, with a Show or hide the URL control.
  • A URL is validated against Discord’s own shape — it must start with https://discord.com/api/webhooks/ — before it is saved at all.

If a URL leaks, delete the webhook in Discord. Removing it from BeamJoy stops BeamJoy posting; only Discord can stop everyone else.

curl on the PATH. BeamMP’s plugin Lua has no HTTP client of its own, so every post is handed to curl as a detached background process — the server never waits on Discord, and a slow or unreachable Discord cannot stall the game.

curl ships with Windows 10 version 1803 and later and with virtually every Linux distribution. If it is missing, BeamJoy says so once in the server log — “Discord posts need curl on the server machine’s PATH, and it wasn’t found” — and simply does not post.

The JSON body goes through a small file in BeamJoyData/discord rather than the command line, so quoting and code pages are never an issue.

Discord allows roughly 30 posts a minute per webhook. BeamJoy queues per webhook and spaces posts about two seconds apart, and each queue is capped so a burst — a twenty-car race finishing, a busy chat — cannot pile up indefinitely.

In practice this means results and votes always arrive, and Player chat on a busy server is the one option that can reach the cap. Give chat its own webhook if you want it, rather than putting it on the same one as results.

  • Posts are fire-and-forget. BeamJoy does not learn whether Discord accepted a post; a wrong URL fails silently, which is what Send test post is for.
  • It is one-way. Nothing in Discord can act on the server. Moderation stays in game and in the console.
  • The server’s name is the posting username, taken from Core Config, so rename the server and the posts rename themselves.