Docs Tutorials
Documentation
Discord Bot Tutorials
Step-by-step guide to using the Team Up Discord bot for tracking Elo ratings and competitive matches
Looking for a specific command?
The command reference lists every command and subcommand with its options, defaults, and who can run it.
Getting Started
1. Invite the Bot
Add the Team Up bot to your Discord server. The bot needs basic permissions to send messages and manage roles (for tier assignments).
Add Bot to Server →2. Set Default Leaderboard (Optional)
If you plan to use multiple leaderboards, set a default one to use when no leaderboard is specified. It lives on the dashboard: your league → Discord → Command Defaults.
/config server Shows the current default (and everything else) in Discord, with a button through to that page
3. Record Your First Match
Start tracking matches immediately! Use the quick command for 1v1 matches. The leaderboard will be created automatically.
/record_match quick opponent:@player2 winner:I won That's it! Your leaderboard is now live.
4. Display Leaderboard
Create an auto-updating leaderboard message in any channel to see the rankings.
/leaderboard display_leaderboard rating_type:Global Shows the global leaderboard with all players
Recording Matches
Quick 1v1 Matches
The fastest way to record a simple 1v1 match.
/record_match quick opponent:@player2 winner:I won Quick command when you win
/record_match quick opponent:@player2 winner:Opponent won Quick command when opponent wins
Standard Match Recording
Record matches with full placement details. Works for 1v1, teams, and free-for-all formats.
1v1 Match
/record_match elo 1st_place:@player1 2nd_place:@player2 Player1 wins, Player2 loses
2v2 Team Match
/record_match elo 1st_place:(@player1 @player2) 2nd_place:(@player3 @player4) Group teammates with parentheses
Free-For-All (4 players)
/record_match elo 1st_place:@winner 2nd_place:@second 3rd_place:@third 4th_place:@fourth List placements in order
Undo Mistakes
Made a mistake? Undo the last recorded match.
/record_match undo Reverts the most recent match
Manual Rating Adjustments
Manually specify exact rating changes (for special cases or corrections).
/record_match manual 1st_place:@player1 1st_place_delta:25 2nd_place:@player2 2nd_place_delta:-25 Player1 gains 25 rating, Player2 loses 25
Managing Leaderboards
Display a Leaderboard
Create an auto-updating leaderboard message in any channel.
/leaderboard display_leaderboard rating_type:Global Shows the global leaderboard (all match types)
Display Match History
Show recent matches in a channel.
/leaderboard display_history limit:10 Shows the 10 most recent matches
Configure Elo Settings
Customize how Elo ratings are calculated. See the configuration reference for all available options.
Open Rating Rules
Rating settings are edited on the dashboard: your league → the leaderboard → Rating Rules.
In Discord, /config leaderboard shows the current values with a button straight to that page.
K-Factor
Controls how much ratings change per match (default: 32)
Starting rating
Rating new players begin on (default: 1200)
Matches Required for Ranking
Players need this many matches before appearing on the leaderboard
View Configuration
Check your current leaderboard settings.
/config leaderboard Shows all current configuration values
Creating Tiers
Elo-Based Tiers
Automatically assign Discord roles when players reach certain Elo ratings.
Add them on the dashboard: Discord Management → Tier Roles. Each tier is an Elo threshold and the role to grant.
Elo ≥ 1800 → @Diamond
Players with 1800+ rating get the Diamond role
Elo ≥ 1500 → @Platinum
Players with 1500+ rating get the Platinum role
Rank-Based Tiers
Assign roles based on leaderboard position (e.g., top 10, top 50).
Top 1 → @Champion
The #1 player gets the Champion role. Same page — pick Rank instead of Elo when adding the tier.
View Tiers
See all configured tiers for your leaderboards.
/config tiers Shows all tier configurations
Customization
Customize Leaderboard Appearance
Add branding to your leaderboard with custom names, icons, and colors.
/profile leaderboard View a leaderboard's current identity and get a direct link to edit its name, description, colors, and images on the Branding page in the web dashboard
Player Profiles
Players can customize their own profile appearance on the web dashboard.
/profile player Shows your current profile and a direct link to edit your display name, colors, and avatar on the web
Server Profile
Customize your server's appearance on the public leaderboard website.
/profile server View your server's current identity and get a direct link to edit its public display name, colors, and images on the Branding & Identity page in the web dashboard
Advanced Features
Channel Configuration
Associate specific leaderboards with Discord channels for auto-detection.
Map them on the dashboard: Discord Management → Channel Mappings.
#match-recording → ranked, results posted to #match-results
Matches recorded in the mapped channel use that leaderboard automatically. /config channel shows a channel's mapping in Discord.
Backup & Import
Export your leaderboard data or import from another source.
/backup export leaderboard:"default" Exports all data as a JSON file
/backup import data_file:[attach-file] leaderboard:"default" Imports data from a JSON file
Team Management
Create persistent teams with custom names and track their ratings separately.
/team_admin create team_id:"team-alpha" team_size:3 members:@player1 @player2 @player3 Creates a team called "team-alpha" with 3 members
/record_match team_alias 1st_place:team-alpha 2nd_place:team-beta Record a match using team names instead of @mentions
Hide/Show Players
Hide specific players from leaderboards (useful for bots, test accounts, etc.). Hiding and showing is done on the dashboard — your league → Players for every board at once, or a leaderboard's own Players page to hide someone on just that board.
/config hidden Lists everyone hidden across every leaderboard
/config hidden leaderboard:"my-league" Lists who's hidden on one board — including players auto-hidden for inactivity
Troubleshooting
"Leaderboard not found"
The leaderboard ID doesn't exist or you're using the wrong ID.
- • Use
/leaderboard listto see available leaderboards - • Check for typos in the leaderboard name
- • Set a default leaderboard on the dashboard, under Discord → Command Defaults
"You don't have permission"
Some commands require admin permissions.
- • Check if you have the "Manage Server" permission in Discord
- • Ask a server admin to run the command
- • Recording matches typically doesn't require admin permissions
Bot not responding
The bot may be offline or missing permissions.
- • Check if the bot is online (shows in the member list)
- • Ensure the bot has "Send Messages" permission in the channel
- • Try using the command in a different channel
- • Re-invite the bot if commands don't appear
Tier roles not being assigned
The bot can't assign roles higher than its own.
- • Move the Team Up bot role above the tier roles in Server Settings → Roles
- • Ensure the bot has "Manage Roles" permission
- • Check that the tier is configured correctly with
/config tiers
Rating changes seem wrong
Rating calculations depend on your configuration.
- • Check current settings with
/config leaderboard - • Use the Elo Calculator to test scenarios
- • Rating changes depend on the difference between players (upsets = bigger swings)
- • K-factor controls the magnitude of all changes
Player not appearing on leaderboard
Players may be hidden or not meet ranking requirements.
- • Check if
matches_requiredis set (player needs X matches first) - • Check whether the player is hidden with
/config hidden - • Check
inactive_days_threshold- inactive players may be hidden
