TookBot Documentation

About TookBot

Welcome to the official documentation for TookBot, an all-in-one Discord bot built solo and hosted on a dedicated VPS in Germany. Whether you run a small community or a server with thousands of members, TookBot gives you the tools to entertain, moderate and configure your server without the headaches.

Key points

• 130+ slash commands covering collectible cards, guilds, music, moderation, automod, temp voice channels, XP, mini-games, tickets, social alerts and more
• Free and paywall-free on the essentials: music volume, skip, multi-source Spotify, moderation, XP
• Hosted in Europe (Hetzner Cloud, Falkenstein) with auto-restart and 24/7 monitoring
• Full web dashboard through Discord OAuth, so you can configure everything without typing commands
• A solo dev you can actually reach: direct support, answers within 24h on the server

Invite TookBot

To add TookBot to your server you need to be an Administrator or hold the "Manage Server" permission.

1. Click the Invite TookBot button
2. Pick your server from the dropdown
3. Review the requested permissions (Admin keeps things simple, otherwise tick at least: Read Messages, Send Messages, Embed Links, Manage Roles, Ban, Kick)
4. Click Authorize
5. Complete the Discord captcha if you get one

Check that TookBot is connected

Once invited, type /ping in any channel. TookBot should reply with its latency in milliseconds. If nothing happens, make sure the bot shows as online in the member list and that it can see the channel.

First-time setup

Once TookBot is invited, the basic configuration happens through the /setup command right inside Discord, or from the web dashboard.

1. Run /setup

   An embed appears with a dropdown for every key channel.

2. Set the welcome channel

   This is where new members get greeted. You can customise the message with /setwelcome or the dashboard builder.

3. Set the log channel

   Sanctions, moderation actions and joins/leaves are posted here. Create a #mod-logs channel that only your mods can see.

4. Set the moderator role

   Pick the role that gets access to the mod commands (warn, kick, ban and so on) without handing it Discord Admin rights.

Web dashboard

The web dashboard lives at dashboard.tookbot.click. You log in with Discord OAuth (no password to create).

What you can do from the dashboard

• Turn each feature on or off per server with on/off toggles
• Configure per-role permissions for every mod command
• Visual builders: tickets, reaction roles, social alerts, custom commands
• Read live stats: active members, top commands, activity heatmap, top music tracks
• Drive the music: watch the live queue and pause/resume/skip from your browser
• Manage promo codes (generate, hand out, track redemptions)
• Moderation: review warns and logs, manage sanctions

Permissions and roles

TookBot works with two separate permission layers:

1. Native Discord permissions

Commands that change your server (kick, ban, clear) require the matching Discord permissions on the user AND on TookBot. If TookBot cannot ban someone, its role is probably too low in the hierarchy.

2. TookBot per-role permissions

In the dashboard Permissions tab you can grant specific mod commands (warn, modlogs, clear) to a moderator role without handing it Discord Admin rights. This is the recommended way to keep a tidy staff team.

🎵 Music: overview

TookBot plays music in your voice channels from 4 free sources: YouTube, SoundCloud, Spotify (track / album / playlist) and Bandcamp. No music feature sits behind a paywall, unlike Jockie or Hydra.

Highlights

• A queue of up to 50 tracks per YouTube or Spotify playlist
• Volume adjustable from 0 to 200% (free, where competitors make it Premium)
• Skip to position N (jump straight to the Nth title in the queue)
• Auto-reconnect if the voice connection drops
• Queue restored automatically after a bot restart
• Persistent listening stats per server (top tracks, top listeners, total time)

Supported music sources

YouTube

The main source. Accepts video links (youtube.com/watch?v=...), short links (youtu.be/...) and playlists (youtube.com/playlist?list=...). Keyword searches run an automatic /search on YouTube.

/play https://www.youtube.com/watch?v=dQw4w9WgXcQ
/play https://www.youtube.com/playlist?list=PLxxxx
/play never gonna give you up

SoundCloud

Single tracks and sets are supported. Paste the soundcloud.com/artist/track URL straight into /play.

/play https://soundcloud.com/artist/track-name

Spotify

Spotify does not allow its audio to be streamed (DRM). TookBot reads the Spotify metadata (title + artist) and plays the equivalent from YouTube. Tracks, albums and playlists are supported.

/play https://open.spotify.com/track/xxx
/play https://open.spotify.com/album/xxx
/play https://open.spotify.com/playlist/xxx

Bandcamp

Single tracks and albums. Paste the Bandcamp URL directly.

/play https://artist.bandcamp.com/track/song

Music commands

Listening statistics

TookBot records every playback in a dedicated table. You can read the stats with /musicstats in Discord or from the dashboard Music tab.

What /musicstats shows

• Total plays over the period
• Number of unique tracks played
• Number of unique listeners (anyone who queued at least one track)
• Total accumulated listening time
• Top 10 most played tracks
• Top 5 listeners (the members who queued the most tracks)
• Breakdown by source (YouTube / SoundCloud / Bandcamp / Twitch)

/musicstats             # last 30 days by default
/musicstats period:7    # last 7 days
/musicstats period:365  # 1 year

Driving the music from the dashboard

The dashboard Music tab lets you do everything from the browser, without opening Discord.

• See the current title with its thumbnail and duration
• Pause / Resume / Skip / Stop / Leave buttons
• Add a track through the "Add a track" field (anything goes: link, title, YT playlist, Spotify URL)
• See the full queue and remove any specific track from it
• Listening stats with a period selector (7 / 30 / 90 / 365 days)

🛡️ Moderation: overview

TookBot ships the classic moderation tools (warn, kick, ban, clear) with persistent logs and per-role permissions you configure from the dashboard.

Moderation commands

🤖 Automatic moderation (TookBot+)

Automod runs in the background and applies 4 toggleable rules to every message and every new member. Admins and users with the Manage Messages permission are exempt automatically.

Available rules

• Banned words: a CSV list of forbidden words, whole-word match, case-insensitive. Action: delete the message + log embed.
• Discord invite blocking: detects any discord.gg/* or discord.com/invite/* link. Action: delete + log.
• Mention spam: configurable threshold (2-50). If a message holds at least that many mentions (users + roles), it gets deleted.
• Anti-raid: a joins-per-minute threshold. If it is crossed, an alert is logged in the admin channel (no auto-kick, to avoid false positives).

🔊 Temporary voice channels

Set up a "lobby" voice channel: when a member joins it, the bot creates a personal voice channel named after them in the configured category and moves them into it. The channel is deleted as soon as it is empty.

Admin setup

1. Create a voice channel such as ➕ Create your channel
2. (Optional) Create a Temp voice category
3. Type /tempvoice setup lobby:<lobby> categorie:<cat> nom_par_defaut:{user}'s channel

User commands (channel owner)

📊 Server analytics

The dashboard /analytics page shows live stats computed from the logs: activity per day, member growth (joins/leaves/cumulative net), a 7x24 heatmap, top commands and top users over 30 days.

• 5 stat cards with a delta against yesterday
• Activity line chart over 7/30/90 days
• Joins/leaves bar chart plus a cumulative net line
• Colour-coded heatmap to spot your busiest hours

Warn system

Warns are stored per server and can be reviewed with /modlogs <member>. You can set an auto-timeout threshold from the dashboard.

Default behaviour

• 1 warn: a DM is sent to the member with the reason
• 3 warns: automatic 1h timeout (configurable)
• 5 warns: automatic 24h timeout (configurable)
• Expired warns can be cleared with /clearwarns

Per-role permissions

Rather than handing Discord Admin rights to your mods, TookBot lets you map each mod command to a specific role from the dashboard.

Example mapping

• Helper role: access to /warn, /note, /clear
• Mod role: everything Helper has plus /kick, /modlogs, /clearwarns
• Admin role: everything Mod has plus /ban, /setup, /setwelcome

Set this up from dashboard, Permissions tab.

Welcome message

Type /setwelcome [channel] to open a visual builder. You can configure:

• The message text (with the {user}, {server} and {count} variables)
• A custom image or banner
• The embed colour
• An automatic mention of the new member
• A role granted automatically on arrival (autorole)

⭐ XP & levels: overview

Message-based XP with an anti-spam cooldown. Every message earns XP that pushes the member up through the levels, and levels can unlock roles automatically.

XP commands

Customisable profile cards

/level shows a card with your avatar, your level, your progress towards the next one and your server rank. Premium users can customise the background, the colour and the badges from the dashboard Premium tab.

Seasonal pass

Every month brings a pass with missions and unlockable rewards (XP boost, rare sabers, cosmetics). Type /pass to check your progress and claim your rewards.

🃏 Collectible cards: overview

A Mudae-style collecting system: roll character cards (anime, video games, movies and shows) from a catalogue of 19,000+ characters, earn the Essences ✨ currency, push your cards up in stars, apply cosmetic borders, take on raid bosses, trade with other players and climb the leaderboards.

Rolls & Essences

/roll pulls a random card. The cooldown is 1h per server (each server has its own timer, so being in several servers means more rolls). Every roll pays out Essences ✨ based on the card rarity (a duplicate pays double). Essences are spent in the shop, on recycling and on founding a guild.

Fusion, rarity upgrades & cosmetics

Push your cards further: fusion adds stars (up to 5⭐), and /cardup turns 5⭐ cards into a card of the rarity above. Borders are cosmetics bought in the shop.

Raid bosses & the grading system

Raid bosses show up in the card channel: up to 5 players fight them as a team with their cards and a role (DPS, Guardian/tank, Healer). A link opens a live battle page on the dashboard. At the end, every player gets a grade from A to F based on their contribution (damage dealt, damage tanked, healing done), and that grade decides their rewards: Essences, rolls, cards and fragments.

Wishlist, trades & leaderboards

Add cards to your wishlist to get notified when someone rolls them, trade cards with other players (uneven trades allowed, 4 against 1 for example), and measure yourself against the leaderboards.

Every card command

Type /cardhelp in Discord for the full in-game guide, or find every command explained on the Commands page.

🛡️ Guilds (clubs): overview

Guilds are cross-server clubs (up to 30 members, from any server TookBot is in) that level up (60 max). As it levels, a guild unlocks passive bonuses for every member: % Essences, % XP, a shorter roll cooldown, better boss loot, a bank and a guild shop. Guild XP comes from rolls, boss wins, the wheel, fusions and donations.

Guild commands

🎫 Tickets

A ticket panel so your members can open a private channel with the staff. Automatic transcripts on close, mod claiming, multiple categories.

Set up in 30 seconds

1. Type /ticket in the channel where you want the panel
2. Visual builder: pick the title, the description and the categories (Support / Report / Partnership / etc.)
3. The panel is posted with an "Open a ticket" button
4. When a member clicks it, TookBot creates a private channel visible to them and the staff role

On close, TookBot generates an HTML transcript file and posts it in the log channel.

🎨 Reaction roles

Lets members give themselves roles by clicking emojis or buttons.

/rolereaction create

The builder offers 2 modes:

• Emoji reactions: reactions are added to a message, each reaction maps to a role
• Buttons: a message with coloured buttons, each button maps to a role

You can create exclusive groups (only one role from the group at a time, for example one pronoun or one favourite game).

📢 Twitch / YouTube / Reddit alerts

TookBot watches the accounts you choose and posts a notification in the channel you pick whenever:

• A Twitch streamer goes live
• A YouTuber uploads a new video
• A Reddit account posts in a given subreddit

🎉 Giveaways

Giveaways with reaction entries, reroll, cancel and a scheduled ending.

/giveaway create
  prize: 1 month of Nitro Boost
  winners: 1
  duration: 24h

Members react to the message to enter. At the end, TookBot picks the winner or winners at random and announces them.

⚙️ Custom commands

Build your own /cmd <name> commands with a text reply or an embed from the dashboard Custom commands tab. Handy for FAQs, rules and useful links.

⚔️ Lightsaber duels

A full RPG mini-game with turn-based combat, attack/defence mind games, a saber collection, a shop and pass missions.

How it works

Each turn, both players secretly pick an attack (high / middle / low) and a guard. If your opponent attacks where you are guarding, you block. Otherwise they land the hit. First one down to 0 HP loses.

🎮 Counter-Strike 2

Full Steam + Faceit integration with automatic rank roles, real-time skin prices and a valued inventory.

🛡️ League of Legends

Riot profile, Solo/Flex ranks, top masteries and live game detection.

🎉 Fun commands

Small social commands to keep the chat alive.

🎛️ Dashboard: login & overview

Head to dashboard.tookbot.click and click Log in with Discord. You grant read access to your Discord server list (only the servers where you are Admin/Owner and where TookBot is invited).

The overview shows you:

• Activity stats for the selected server (last 7 / 30 days)
• An activity heatmap by hour x day of the week
• Most used commands
• Top music listeners
• The latest moderation events

Turning a feature on

Features tab. Every feature has its own on/off toggle per server. If a member tries to use a disabled command, they get a quiet DM about it (no chat spam).

Music tab

See Driving the music from the dashboard.

Promo codes

Promo codes tab (owner admin only). Generate codes to hand out to your users to grant them Premium, an XP boost or cosmetics.

💎 Premium (cosmetics only)

TookBot Premium unlocks cosmetics only (level card backgrounds, badges, custom colours). No functional feature is gated behind Premium.

To buy it: open the TookBot Discord profile and go to the Store tab.

☕ Donate via Ko-fi

TookBot is built solo and runs on a VPS paid out of my own pocket. If the bot is useful to you, you can buy it a coffee: ko-fi.com/tookbot.

Donors get some recognition:

• A notification in the support channel when a donation lands (with a Donor role)
• A spot on the supporters wall on the site

🛠 Music is not working

Symptom: "This feature is having some trouble"

A friendly message shown when yt-dlp or ffmpeg fails. Possible causes:

• The YouTube video is private, deleted or age-restricted
• WARP (the proxy that works around YouTube anti-bot) is disconnected on the VPS
• The bgutil-pot HTTP server is unreachable
• yt-dlp is out of date (rare, it auto-updates weekly)

Quick fix: try again in a few minutes, or with another video. If it keeps happening, report it on the support server.

Symptom: Spotify "not configured"

The Spotify API keys are not set on the server side. Contact support to get it fixed.

Symptom: SoundCloud "Host unreachable"

The WARP proxy is now routed for YouTube only, so SoundCloud goes out directly. If the error comes back, it is most likely temporary (DNS / network).

Command disabled

If a command replies "This feature is disabled on this server":

1. Go to dashboard.tookbot.click, pick your server, open the Features tab
2. Turn the toggle on for that feature
3. Run the command again (it takes effect immediately)

If a mod command replies "You do not have permission", check the role-to-command mapping in the Permissions tab.

Bot inactive / not responding

• Check that TookBot shows as online in the Discord member list
• Check that it can see the channel (View Channel + Send Messages permissions)
• Check the status on tookbot.click/status
• If it has been offline for a while, the VPS is probably having trouble. Contact support.

Contact support

Bug, question or suggestion: join the TookBot support server.

Answers within 24h, often within the hour. A solo dev you can reach directly.