Skip to main content
Documentation

Competitor Role Sync

Automatically assign a Discord role to confirmed participants in your competition. When someone joins, they get the role. When they leave or are dropped, it's removed. No manual role management needed.

How It Works

When you assign a competitor role to a competition:

  1. All currently confirmed participants with linked Discord accounts are queued for the role
  2. As new participants register and are confirmed, the role is added automatically
  3. When a participant withdraws or is dropped, the role is removed automatically

Role changes are processed in the background -- there may be a short delay (up to 30 seconds) between a status change and the Discord role being applied.

Prerequisites

Before setting up competitor role sync, make sure:

  • Your Discord server is linked to your Tabletop League organization (via the /setup bot command)
  • The bot has "Manage Roles" permission in your Discord server
  • The bot's role is above the target role in your server's role hierarchy (Server Settings > Roles -- drag the bot's role higher than the role you want to assign)
  • Participants have linked their Discord accounts on Tabletop League -- the sync only works for participants with a connected Discord account

Setting Up via Discord Bot

Use the /competitor-role slash command in your linked Discord server.

Assigning a Role

  1. Run /competitor-role with your competition selected and the Set role action
  2. A role picker appears -- select the Discord role you want to assign to competitors
  3. The bot validates it can manage that role (checks role hierarchy)
  4. Existing confirmed participants are immediately queued for the role

Viewing the Current Role

Run /competitor-role with the View current action to see which role is assigned (if any).

Removing the Role

Run /competitor-role with the Remove role action. The role configuration is cleared, and any currently assigned roles are queued for removal.

Syncing (Reconciling)

If roles get out of sync (e.g., someone manually removed a role, or the bot was temporarily offline), run /competitor-role with the Sync (reconcile) action. This re-queues all confirmed participants for role assignment.

Permissions

You need one of the following to use /competitor-role:

  • Manage Server permission in Discord, OR
  • The designated manager role configured during /setup

Setting Up via Web UI

You can also configure the competitor role from the competition's manage area on the website.

  1. Go to your competition's Settings page
  2. Scroll down to the Admin Tools section
  3. In the Competitor Role Sync card:
    • Select the Discord server (if your org has multiple linked servers)
    • Enter the Discord role ID (the numeric snowflake ID of the role)
    • Click Save

To find a role's ID in Discord: enable Developer Mode (User Settings > Advanced > Developer Mode), then right-click the role and select Copy Role ID.

What Gets Synced

| Participant Status Change | Role Action | |--------------------------|-------------| | Registration confirmed / approved | Role added | | Manually added by organizer | Role added | | Participant withdraws | Role removed | | Dropped by organizer | Role removed | | Eliminated or withdrawn from a stage (if "remove from eliminated players" is on) | Role removed | | A match result is corrected, un-eliminating a player | Role re-added |

Only participants with a Discord account linked to their Tabletop League profile are affected. Participants without a linked Discord account are silently skipped.

Removing the Role When Players Are Eliminated

By default, the competitor role stays on a participant for the whole competition. If you'd rather have it removed once a player is knocked out, turn on Remove role from eliminated players in the Competitor Role Sync card (web UI).

When this is on:

  • Bracket players (single/double elimination): the role is removed as soon as their knockout match result is confirmed and they're out — you don't have to finalize the stage first. (If your competition requires result verification, this happens once the result is verified, not the instant it's submitted. Losing the upper-bracket match in double elimination does not count — that player drops to the losers bracket and keeps the role.)
  • Group, round-robin, swiss, and league players: the role is removed when you finalize the stage and they aren't among the players who advance.
  • Withdrawn players: the role is removed when they're marked withdrawn from a stage.
  • Turning the setting on mid-competition: anyone already eliminated has their role removed once, right away — you don't have to re-process them by hand.

If a match result is later corrected so a player is no longer eliminated, their role is automatically added back.

For more on exactly when a player counts as "eliminated", see Competition Formats.

Troubleshooting

Roles aren't being assigned

  • Check bot permissions -- the bot needs "Manage Roles" in your Discord server
  • Check role hierarchy -- the bot's highest role must be positioned above the competitor role in Server Settings > Roles
  • Check Discord link -- participants need a Discord account linked on their Tabletop League profile
  • Wait a moment -- role changes are processed every 30 seconds, so there's a short delay

"Missing Permissions" or "Missing Access" errors

The bot can't manage the selected role. This usually means:

  • The bot's role is below the target role in the hierarchy -- move it higher
  • The bot lost the "Manage Roles" permission -- re-check its role permissions

Role was manually removed from a user

Run /competitor-role with the Sync (reconcile) action to re-apply roles to all confirmed participants.

Changing the competitor role

Run /competitor-role with Set role again and pick a new role. The old role assignments are not automatically removed -- you'll need to remove the old role manually in Discord if desired.