TookBot Documentation

À propos de TookBot

Bienvenue sur la documentation officielle de TookBot, un bot Discord tout-en-un développé en solo et hébergé sur un VPS dédié en Allemagne. Que tu gères une petite communauté ou un serveur de plusieurs milliers de membres, TookBot fournit les outils pour animer, modérer et configurer ton serveur sans prise de tête.

Points clés

• 90+ commandes slash couvrant musique, modération, automod, salons vocaux temp, XP, mini-jeux, tickets, alertes sociales et plus
• Gratuit et sans paywall sur l'essentiel : volume musique, skip, multi-source Spotify, modération, XP
• Hébergé en Europe (Hetzner Cloud, Falkenstein) avec auto-restart et monitoring 24/7
• Dashboard web complet via OAuth Discord pour configurer sans taper de commandes
• Dev solo accessible : support direct, réponses en moins de 24h sur le serveur

Inviter TookBot

Pour ajouter TookBot à ton serveur, tu dois être Administrateur ou avoir la permission "Gérer le serveur".

1. Clique sur le bouton Inviter TookBot
2. Choisis ton serveur dans la liste déroulante
3. Vérifie les permissions demandées (Admin recommandé pour simplifier, sinon coche au minimum : Lire les messages, Envoyer messages, Embed Links, Gérer rôles, Bannir, Expulser)
4. Clique Autoriser
5. Complète le captcha Discord si demandé

Vérifier que TookBot est bien connecté

Après l'invitation, tape /ping dans n'importe quel salon. TookBot doit répondre avec sa latence en millisecondes. Si rien ne se passe, vérifie que le bot est en ligne dans la liste des membres et qu'il a accès au salon.

Configuration initiale

Une fois TookBot invité, la configuration de base se fait via la commande /setup directement sur Discord, ou depuis le dashboard web.

1. Lance /setup

   Un embed apparaît avec des menus déroulants pour chaque salon clé.

2. Définis le salon de bienvenue

   C'est là que les nouveaux membres seront accueillis. Tu pourras customiser le message via /setwelcome ou le builder du dashboard.

3. Définis le salon de logs

   Sanctions, actions modération, joins/leaves seront publiés ici. Crée un salon #logs-mod visible uniquement par tes mods.

4. Configure le rôle modérateur

   Sélectionne le rôle qui aura accès aux commandes mod (warn, kick, ban, etc.) sans lui filer les droits Admin Discord.

Dashboard web

Le dashboard web est disponible sur dashboard.tookbot.click. Connexion via OAuth Discord (aucun mot de passe à créer).

Ce que tu peux faire depuis le dashboard

• Activer / désactiver chaque feature par serveur via des toggles on/off
• Configurer les permissions par rôle pour chaque commande mod
• Builders visuels : tickets, rôles-réaction, alertes social, commandes custom
• Consulter les stats temps réel : membres actifs, top commandes, heatmap d'activité, top pistes musicales
• Piloter la musique : voir la queue live, pause/resume/skip depuis le navigateur
• Gérer les promo codes (générer, distribuer, suivre les redemptions)
• Modération : consulter les warns, logs, gérer les sanctions

Permissions et rôles

TookBot utilise deux niveaux de permissions distincts :

1. Permissions Discord natives

Les commandes qui modifient ton serveur (kick, ban, clear) nécessitent les permissions Discord correspondantes sur l'utilisateur ET sur TookBot. Si TookBot ne peut pas bannir quelqu'un, son rôle est probablement trop bas dans la hiérarchie.

2. Permissions par rôle TookBot

Depuis le dashboard, onglet Permissions, tu peux donner accès à certaines commandes mod (warn, modlogs, clear) à un rôle modérateur, sans lui filer les droits Admin Discord. C'est la méthode recommandée pour avoir une équipe staff cadrée.

🎵 Musique : vue d'ensemble

TookBot lit de la musique dans tes salons vocaux depuis 4 sources gratuites : YouTube, SoundCloud, Spotify (track / album / playlist) et Bandcamp. Aucune feature musique n'est derrière un paywall, contrairement à Jockie ou Hydra.

Points forts

• File d'attente jusqu'à 50 pistes par playlist YouTube ou Spotify
• Volume ajustable de 0 à 200% (gratuit, là où c'est Premium chez les concurrents)
• Skip à la position N (saute directement au Nème titre de la queue)
• Reconnect auto si la connexion vocale drop
• Reprise auto de la file après redémarrage du bot
• Stats d'écoute persistantes par serveur (top pistes, top auditeurs, temps total)

Sources musicales supportées

YouTube

Source principale. Accepte les liens vidéo (youtube.com/watch?v=...), les liens courts (youtu.be/...) et les playlists (youtube.com/playlist?list=...). Les recherches par mots-clés font un /search automatique sur YouTube.

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

SoundCloud

Pistes individuelles et sets supportés. Colle directement l'URL soundcloud.com/artist/track dans /play.

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

Spotify

Spotify ne permet pas de streamer son audio (DRM). TookBot extrait les métadonnées Spotify (titre + artiste) puis joue l'équivalent depuis YouTube. Tracks, albums et playlists supportés.

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

Bandcamp

Pistes individuelles et albums. Colle l'URL Bandcamp directement.

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

Commandes musique

Statistiques d'écoute

TookBot enregistre chaque lecture musicale dans une table dédiée. Tu peux consulter les stats avec /musicstats sur Discord ou depuis le dashboard onglet Musique.

Ce que /musicstats affiche

• Total de lectures sur la période
• Nombre de pistes uniques jouées
• Nombre d'auditeurs uniques (ceux qui ont ajouté au moins une piste)
• Temps total d'écoute cumulé
• Top 10 pistes les plus jouées
• Top 5 auditeurs (utilisateurs qui ont fait jouer le plus de pistes)
• Breakdown par source (YouTube / SoundCloud / Bandcamp / Twitch)

/musicstats             # 30 derniers jours par defaut
/musicstats periode:7   # 7 derniers jours
/musicstats periode:365 # 1 an

Pilotage musique depuis le dashboard

L'onglet Musique du dashboard te permet de tout faire depuis le navigateur, sans avoir à ouvrir Discord.

• Voir le titre en cours avec thumbnail et durée
• Boutons Pause / Resume / Skip / Stop / Leave
• Ajouter une piste via le champ "Ajouter une musique" (accepte tout : lien, titre, playlist YT, URL Spotify)
• Voir la file d'attente complète avec possibilité de retirer une piste précise
• Stats d'écoute avec sélecteur de période (7 / 30 / 90 / 365 jours)

🛡️ Modération : vue d'ensemble

TookBot fournit les outils de modération classiques (warn, kick, ban, clear) avec un système de logs persistants et des permissions par rôle configurables depuis le dashboard.

Commandes de modération

🤖 Modération automatique (TookBot+)

L'automod tourne en arrière-plan et applique 4 règles toggleables sur chaque message / nouveau membre. Les admins et users avec la permission Manage Messages sont exempts automatiquement.

Règles disponibles

• Mots interdits : liste CSV de mots interdits, match du mot entier, case-insensitive. Action : delete message + log embed.
• Anti-invites Discord : detecte tout lien discord.gg/* ou discord.com/invite/*. Action : delete + log.
• Spam mentions : seuil configurable (2-50). Si le message contient ≥ seuil mentions (users + rôles), il est supprimé.
• Anti-raid : seuil joins/minute. Si dépassé, log une alerte dans le salon admin (pas de kick auto pour éviter les faux positifs).

🔊 Salons vocaux temporaires

Configure un salon vocal "lobby" : quand un membre le rejoint, le bot crée un vocal perso à son nom dans la catégorie configurée et l'y déplace automatiquement. Le salon est détruit dès qu'il est vide.

Setup admin

1. Crée un vocal style ➕ Créer ton salon
2. (Optionnel) Crée une catégorie Vocaux temp
3. Tape /tempvoice setup lobby:<lobby> categorie:<cat> nom_par_defaut:Vocal de {user}

Commandes user (owner du salon)

📊 Analytics serveur

Page dashboard /analytics avec stats live calculées depuis les logs : activité par jour, croissance membres (joins/leaves/net cumulé), heatmap 7×24, top commandes et top users sur 30 jours.

• 5 stat cards avec delta vs hier
• Line chart activité 7/30/90 jours
• Bar chart joins/leaves + ligne nette cumulée
• Heatmap colorée pour repérer les pics horaires

Système de warns

Les warns sont persistants par serveur et consultables via /modlogs <membre>. Tu peux configurer un seuil d'auto-timeout depuis le dashboard.

Comportement par défaut

• 1 warn → DM envoyé au membre avec la raison
• 3 warns → timeout 1h auto (configurable)
• 5 warns → timeout 24h auto (configurable)
• Les warns expirés peuvent être révoqués via /clearwarns

Permissions par rôle

Plutôt que de filer les droits Admin Discord à tes mods, TookBot te permet de mapper chaque commande mod à un rôle précis depuis le dashboard.

Exemples de mapping

• Rôle Helper → accès à /warn, /note, /clear
• Rôle Mod → tout Helper + /kick, /modlogs, /clearwarns
• Rôle Admin → tout Mod + /ban, /setup, /setwelcome

Configure ça depuis dashboard → onglet Permissions.

Message de bienvenue

Tape /setwelcome [salon] pour ouvrir un builder visuel. Tu peux configurer :

• Texte du message (avec variables {user}, {server}, {count})
• Image / bannière custom
• Couleur de l'embed
• Mention automatique du nouveau membre
• Rôle attribué automatiquement à l'arrivée (autorole)

⭐ XP & Niveaux : vue d'ensemble

Système d'XP par message avec cooldown anti-spam. Chaque message gagne de l'XP qui fait monter le membre en niveau. Les niveaux peuvent débloquer des rôles automatiques.

Commandes XP

Cartes profil personnalisables

/niveau affiche une carte avec ton avatar, ton niveau, ta progression vers le suivant et ton rang serveur. Les utilisateurs Premium peuvent personnaliser le background, la couleur et les badges depuis l'onglet Premium du dashboard.

Pass saisonnier

Chaque mois un pass avec missions et récompenses débloquables (XP boost, sabres rares, cosmétiques). Tape /pass pour voir ta progression et claim tes récompenses.

🎫 Tickets

Panneau de tickets pour que tes membres ouvrent un salon privé avec le staff. Transcripts auto à la fermeture, claim mod, catégories multiples.

Setup en 30 secondes

1. Tape /ticket dans le salon où tu veux le panneau
2. Builder visuel : choisis titre, description, catégories (Support / Report / Partenariat / etc.)
3. Le panneau est posté avec un bouton "Ouvrir un ticket"
4. Quand un membre clique, TookBot crée un salon privé visible par lui et le rôle staff

À la fermeture, TookBot génère un fichier HTML transcript et le poste dans le salon de logs.

🎨 Rôles-réaction

Permet aux membres de s'attribuer eux-mêmes des rôles en cliquant sur des emojis ou des boutons.

/rolereaction create

Le builder propose 2 modes :

• Reaction emoji : ajoute des réactions sur un message, chaque réaction = un rôle
• Boutons : message avec boutons colorés, chaque bouton = un rôle

Tu peux créer des groupes exclusifs (un seul rôle du groupe à la fois, ex : un seul pronoun, un seul jeu favori).

📢 Alertes Twitch / YouTube / Reddit

TookBot surveille les comptes de ton choix et envoie une notification dans le salon désigné quand :

• Un streamer Twitch passe en live
• Un YouTuber upload une nouvelle vidéo
• Un compte Reddit poste sur un subreddit donné

🎉 Giveaways

Tirages au sort avec entries par réaction, reroll, cancel et fin programmée.

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

Les membres réagissent au message pour participer. À la fin, TookBot pick le ou les gagnants aléatoirement et les annonce.

⚙️ Commandes custom

Crée tes propres commandes /cmd <nom> avec une réponse texte ou un embed depuis le dashboard onglet Commandes custom. Utile pour les FAQ, règles, liens utiles.

⚔️ Duels de sabres laser

Mini-jeu RPG complet avec combat tour par tour, mindgame attaque/défense, collection de sabres, boutique, missions de pass.

Principe

Chaque tour, les deux joueurs choisissent secrètement une attaque (haute / médiane / basse) et une défense. Si l'adversaire attaque où tu défends, tu bloques. Sinon il touche. Le premier à 0 PV perd.

🎮 Counter-Strike 2

Intégration complète Steam + Faceit avec rank role auto, prix de skins en temps réel et inventaire valorisé.

🛡️ League of Legends

Profil Riot, rangs Solo/Flex, top masteries et détection de game en cours.

🎉 Commandes fun

Mini-commandes sociales pour animer le chat.

🎛️ Dashboard : connexion & overview

Va sur dashboard.tookbot.click et clique Connexion Discord. Tu autorises l'accès en lecture à ta liste de serveurs Discord (uniquement les serveurs où tu es Admin/Owner et où TookBot est invité).

L'overview te montre :

• Stats activité du serveur sélectionné (7 / 30 derniers jours)
• Heatmap d'activité par heure × jour de la semaine
• Top commandes utilisées
• Top auditeurs musique
• Derniers événements de modération

Activer une fonctionnalité

Onglet Fonctionnalités. Chaque feature a un toggle on/off propre au serveur. Si un membre tente d'utiliser une commande désactivée, il reçoit un message discret en MP (pas de spam dans le chat).

Onglet musique

Voir Pilotage musique depuis le dashboard.

Promo codes

Onglet Promo codes (admin owner uniquement). Génère des codes à distribuer à tes utilisateurs pour leur offrir Premium, XP boost, ou cosmétiques.

💎 Premium (cosmétique uniquement)

Premium TookBot débloque uniquement des cosmétiques (background de carte de niveau, badges, couleurs custom). Aucune feature fonctionnelle n'est gated derrière Premium.

Pour acheter : ouvre le profil Discord de TookBot → onglet Boutique.

☕ Soutenir via Ko-fi

TookBot est développé en solo et tourne sur un VPS payé de ma poche. Si le bot te rend service, tu peux offrir un café : ko-fi.com/tookbot.

Les donateurs sont reconnus :

• Notification dans le salon support quand un don arrive (avec rôle Donateur)
• Affichage dans le mur des soutiens sur le site

🛠 Musique ne marche pas

Symptôme : "Cette fonctionnalité a quelques soucis"

Message friendly affiché quand yt-dlp ou ffmpeg échoue. Causes possibles :

• Vidéo YouTube privée, supprimée ou age-restricted
• WARP (proxy contournement anti-bot YouTube) déconnecté côté VPS
• bgutil-pot HTTP server inaccessible
• yt-dlp pas à jour (rare, auto-update hebdomadaire)

Solution rapide : réessaie dans quelques minutes, ou avec une autre vidéo. Si ça persiste, signale sur le serveur support.

Symptôme : Spotify "pas configuré"

Les clés API Spotify ne sont pas définies côté serveur. Contacte le support pour corriger.

Symptôme : SoundCloud "Host unreachable"

Le proxy WARP est routé pour YouTube uniquement maintenant. SoundCloud passe en direct. Si l'erreur revient, c'est probablement temporaire (DNS / réseau).

Commande désactivée

Si une commande répond "Cette fonctionnalité est désactivée sur ce serveur" :

1. Va sur dashboard.tookbot.click → ton serveur → onglet Fonctionnalités
2. Active le toggle de la feature concernée
3. Réessaie la commande (effet immédiat)

Si une commande mod répond "Tu n'as pas la permission", vérifie le mapping rôle → commande dans l'onglet Permissions.

Bot inactif / ne répond pas

• Vérifie que TookBot est en ligne dans la liste des membres Discord
• Vérifie qu'il a accès au salon (permissions Voir le salon + Envoyer messages)
• Vérifie le statut sur tookbot.click/status
• Si offline depuis longtemps, le VPS a probablement un souci. Contacte le support.

Contact support

Bug, question, suggestion : rejoins le serveur de support TookBot.

Réponses en moins de 24h, souvent dans l'heure. Dev solo accessible directement.