Skip to content

Create the Discord app

Every judgebot is its own Discord application, owned by whoever runs it. This page covers the steps from creating the application to /judge answering in your server. Discord’s walkthrough, Building your first Discord Bot, covers the same portal screens in general terms. The steps below say what to choose for this bot.

The bot uses slash commands only. It needs no privileged gateway intents and no channel permissions. It receives only its own commands and button presses, and replies through the interaction, so it is never granted the ability to read messages.

  • The first run done up to the point where the web app answers: the database is up and the data is loaded. Nothing on this page spends money.
  • The Manage Server permission in the Discord server you are adding the bot to. Adding an app to a server requires it (Installation Context).
  • A Discord account with email verified, which the developer portal requires.

Open the Developer Portal and choose New Application. Members see the name beside /judge in the command picker and on the bot’s profile, so name it for your server (“Rules Judge”, “Club Judge”).

The App Icon is the bot’s avatar. Any image works. The project’s icon is a 512×512 PNG (assets/icon.png in the repository) if you want it. Nothing else on the General Information page matters to the bot. The Application ID shown there ends up in the install link in step 3.

Under Bot:

  1. Choose Reset Token and copy the result. Discord shows a token once. If you lose it, reset again. The token is a credential for the application, and every binary that reads it keeps it redacted. Then, in the config editor (scripts/config.sh), Settings tab:

    • DISCORD_TOKEN: Set…, paste the token
    • JUDGE_OPERATOR_DISCORD: your own Discord username. The bot does not start without it, and /help and /license show it.

    By hand, the same two lines go in .env.

  2. Leave all three Privileged Gateway Intents (Presence, Server Members, Message Content) off. The bot connects with no intents (Gateway Intents explains what they are). Turning one on changes nothing in the bot. Past 100 servers it would trigger Discord’s verification process for nothing.

  3. Public Bot can be off. It controls whether other people can use your install link, which a bot for your own servers does not need.

Under OAuth2 → URL Generator:

  1. Tick the scopes bot and applications.commands. bot puts a bot user in the server. applications.commands lets it register slash commands there (OAuth2 scopes).
  2. Under Bot Permissions, tick nothing. Replies, buttons and the “did you mean?” row all go through the interaction, which needs no channel permission. The URL ends in permissions=0.
  3. Open the generated URL in your browser, pick the server, and Authorize. This is Discord’s bot authorization flow. The URL has the shape https://discord.com/oauth2/authorize?client_id=<application id>&scope=bot%20applications.commands&permissions=0. You can reuse it for every server you administer.

The portal’s newer Installation page (installation contexts and a Discord-provided install link) does the same job. If you use it instead, choose:

  • Guild Install as the only context. The bot has no user-install behaviour.
  • The same two scopes.
  • No permissions.

The bot registers its own slash commands when it starts. It registers them either:

  • in one server, where they appear instantly. Other servers the bot is in, and DMs with the bot, get no commands. Or:
  • globally, in every server the bot is in, where they take up to an hour to appear. /card, /rule, /help, /license and /forget then work in a DM with the bot too. /judge and /judge-private are server-only either way.

See Registering a command. For a bot in one or two servers, register in the server:

  1. In Discord, User Settings → Advanced → Developer Mode on.
  2. Right-click the server icon → Copy Server ID (Discord’s help article Where can I find my User/Server/Message ID?).
  3. Put it in .env as GUILD_ID.

Leave GUILD_ID unset to register globally.

Avoid switching back and forth. The bot registers the set it is configured for and does not remove the other. Members would see two identical /judge entries from the same bot until the stale set is cleared. The portal does not clear it. Overwriting the set with an empty list does (Bulk Overwrite Guild Application Commands). You need the bot token, the Application ID from step 1 and, to clear a server’s set, the server id GUILD_ID held before you blanked it:

Terminal window
DISCORD_TOKEN=... # as in .env
APPLICATION_ID=... # General Information → Application ID
GUILD_ID=... # the server the stale set was registered in
# clear the server's set (after moving to global registration)
curl -X PUT -H "Authorization: Bot $DISCORD_TOKEN" -H "Content-Type: application/json" -d '[]' \
"https://discord.com/api/v10/applications/$APPLICATION_ID/guilds/$GUILD_ID/commands"
# clear the global set (after moving to GUILD_ID)
curl -X PUT -H "Authorization: Bot $DISCORD_TOKEN" -H "Content-Type: application/json" -d '[]' \
"https://discord.com/api/v10/applications/$APPLICATION_ID/commands"

Clear only the set the bot is no longer configured for. The bot registers its own set again at every start.

Terminal window
scripts/deploy.sh # or: cargo run --release -p judgebot -- --discord --jobs

The compose service runs --discord unless JUDGE_ROLES in .env leaves it out. If you set JUDGE_ROLES='--api --web --jobs' to try the web app first, clear it or add --discord.

The bot connects about 15 seconds after it starts. It first takes the gateway lease, a lock in the database that keeps a second judgebot from answering beside it, and waits out a grace period. A log line standing by: another instance holds the Discord gateway means another judgebot --discord on the same database is connected. That is usually a container left from a previous deploy; the line names it (Deployment).

The log line registered /judge, /judge-private, /card, /rule, /help, /license and /forget in one guild (or … globally) confirms registration. A warning registering the slash commands failed instead means the bot is connected with whatever commands were registered before (none, on a first start); the next start, such as the next scripts/deploy.sh, tries again. Running /help in the server confirms it end to end. Another bot’s /judge in the same server does not conflict with yours: Discord’s command picker shows each bot’s icon beside its commands.

init uploads the symbols if DISCORD_TOKEN was already set when it ran. Otherwise run this once:

Terminal window
docker compose run --rm refresh emoji # or: cargo run --release -p judgebot -- ingest emoji

It uploads Scryfall’s mana and card symbols as application emoji. These belong to the application, not to any server, and need no emoji permission (Application-owned emoji). Without them, answers show the literal {W}. The command is safe to rerun, reads DISCORD_TOKEN and needs no database.

This step is optional. By default the bot receives commands and button clicks over a gateway connection, and Discord is quiet for a few seconds while a deploy hands it to the new container. Receiving them over HTTP instead keeps them answered during a deploy, but needs a public HTTPS address for the bot: https://<JUDGE_DOMAIN> with the bundled public site, or your own proxy’s or the tunnel’s hostname (Exposure; Deployment has the steps).

  1. Set DISCORD_INTERACTIONS=http in .env and deploy (scripts/deploy.sh). Commands go unanswered until step 2.
  2. In the Developer Portal, open General Information and set Interactions Endpoint URL to https://<your public host>/discord/interactions: with the bundled public site, https://<JUDGE_DOMAIN>/discord/interactions. Discord tests the address before it saves it.

The bot then opens no gateway connection, and shows in the member list without a status dot.

Discord’s requests come from its servers, not a browser, so they cannot pass a challenge. Behind Cloudflare, keep /discord/interactions out of any Managed Challenge rule or Access policy, and turn Bot Fight Mode off (it covers the whole zone and cannot skip a path), or the test and every interaction fail.

The bot answers wherever its commands can be used. That is a Discord setting, not the bot’s. In Server Settings → Integrations, open your application and restrict /judge (or every command) to the channels, roles or members you choose (application command permissions). A rules-questions channel keeps follow-ups together, because history is per channel.

The bot has two limits of its own. Neither applies to /card and /rule.

  • JUDGE_USER_LIMIT questions per member per JUDGE_USER_WINDOW_SECS. The default is six per ten minutes, and 0 turns it off.
  • JUDGE_CONCURRENCY runs in flight at once.

A Partially correct or Incorrect rating asks the rater why, and the reason lands in your feedback queue: the admin page’s Feedback tab, judge-cli queue, or the admin MCP tools (Agents). An Incorrect rating’s confirmation names you. When the repository JUDGE_SOURCE_URL names is on GitHub, it also links that repository’s Wrong or unhelpful ruling issue form. A fork has Issues off until you enable them under the repository’s Settings → General → Features.

Members holding a role named JUDGE_ROLE (default Judge) rate as judges. Their rating overrides the crowd’s smoothed average for that answer. Create the role under Server Settings → Roles (Discord’s Role Management 101 covers it) and give it to the people whose rulings you trust. The name must match exactly. The role needs no permissions of its own.

One application can be in every server you administer. Reuse the install link from step 3 and register commands globally. The servers then share one process, with one spend cap (JUDGE_MAX_USD), one concurrency limit and one judge role name (D16 has the reasoning). A community that wants its own budget runs its own instance: a second copy of the same compose file, with a second application’s token.

Your application is bound by the Discord Developer Policy and Terms of Service like any other. Two points matter for a judgebot:

  • It must not collect more data than it needs. This one stores each question with its channel and the asker’s id and username, ratings per user with the reasons they give, and failed calls with the asker’s id. /forget deletes a user’s ratings and reasons and removes them from their questions and failed calls.
  • Magic content is used under Wizards of the Coast’s Fan Content Policy, which your instance’s /help already states.