bot

A robust Discord bot built with discord.js v14, distube, and TypeScript. Features include music playback, moderation, a leveling/XP system, and server utilities.

⚡ Quick Start

git clone https://github.com/totalo-dev/botdiscord.git cd botdiscord npm install

Create .env in the root: DISCORD_TOKEN=your_token_here

Enable in Discord Developer Portal → Bot → Privileged Gateway Intents:

• ✅ MESSAGE CONTENT INTENT
• ✅ SERVER MEMBERS INTENT

npm run dev # development npm run build && npm start # production

Full setup guide below ↓

Installation

1. Clone the repository

git clone https://github.com/totalo-dev/botdiscord.git cd botdiscord

2. Install dependencies

npm install

3. Create the .env file

Create a .env file in the root of the project with the following content:

DISCORD_TOKEN=your_token_here

The bot token is obtained from the Discord Developer Portal: https://discord.com/developers/applications

4. Configure Discord Privileged Intents

The bot requires 2 mandatory Gateway Intents to be enabled in the Discord Developer Portal.

Go to https://discord.com/developers/applications → select your application → Bot → scroll to Privileged Gateway Intents and enable:

Intent	Required for
MESSAGE CONTENT INTENT	Reading message content to process prefix commands (<command). Without this, the bot starts but never responds to any command.
SERVER MEMBERS INTENT	guildMemberAdd (auto-role), guildMemberRemove (member log), and accurate member counts in <serverinfo. Without this, these features are completely non-functional.
PRESENCE INTENT	Not required — can be left disabled.

⚠️ Both MESSAGE CONTENT and SERVER MEMBERS intents are mandatory. The bot will connect to Discord without them but will be completely unresponsive.

5. Invite scopes and slash commands

When adding the bot to a server, the OAuth2 invite must include both scopes:

Scope	Required for
bot	Bot connection, permissions, messages, moderation, voice, and events
applications.commands	Slash commands (/command)

Slash commands are registered automatically when the bot starts. They are currently registered globally through Discord, so new or changed commands can take a while to appear in servers.

Most commands are available both as prefix commands (<command) and slash commands (/command). At the moment, memberlog, welcome, and poll are prefix-only.

6. (Optional) YouTube cookies

To avoid YouTube blocking issues in production, create a cookies.json file in the root of the project with your YouTube account cookies.

Use cookies.example.json as a reference for the correct format.

Never commit cookies.json (already included in .gitignore). Use a dedicated Google account — never your personal account.

7. Start the bot

Development mode:

npm run dev

Production mode:

npm run build npm start

Automatically created files

File	Created when
data/xp.json	First user gains XP
data/reminders.json	First reminder is set
data/blockedChannels.json	First channel is blocked
data/autoRoles.json	First auto-role is set
data/memberLog.json	First member log is configured
data/welcome.json	First welcome is configured

Project structure

botdiscord/ ├── src/ │ ├── commands/ │ ├── config/ │ ├── events/ │ ├── services/ │ ├── utils/ │ └── index.ts ├── data/ ├── .env ├── cookies.json (optional) ├── cookies.example.json ├── tsconfig.json └── package.json

Features

Slash commands

• All commands support both prefix (<command) and slash commands (/command)
• Slash commands are registered globally on startup
• Slash commands respect the same cooldowns, admin-only restrictions and channel blocking as prefix commands

XP & Rank system

• Users automatically gain XP (15–25) by sending messages, with a 60s cooldown per user
• XP formula to level up: 100 × level²
• On level up, the bot sends a congratulations DM to the user
• Persistent across restarts (data/xp.json)

Reminders

• Users can set DM reminders with a time and message
• Supports s, m, h, d time formats — maximum 7 days
• Reminders persist across restarts and fire immediately if missed (data/reminders.json)

Auto-role

• Automatically assigns a configured role to every new member that joins
• Configured per server by admins
• Persistent across restarts (data/autoRoles.json)

Member log

• Logs member departures to a configured text channel
• Shows username, ID, join date, roles held, and remaining member count
• Can be enabled/disabled per server by admins — no cache is accumulated when disabled
• Persistent across restarts (data/memberLog.json)

Welcome messages

• Sends a customizable welcome message when a new member joins
• Configured per server by admins via <welcome #channel [message]
• Supports {user} and {server} placeholders in the message
• Can be enabled/disabled independently — no cache when disabled
• Persistent across restarts (data/welcome.json)

Channel blocking

• Admins can block specific channels so the bot ignores non-admin commands there
• Admins are always exempt and can use all commands in blocked channels
• Persistent across restarts (data/blockedChannels.json)

Available commands

Commands listed below use the prefix form. All commands are also available as slash commands (/ping, /play, /rank, etc.).

General

Command	Alias	Cooldown	Description
<ping	<p	3s	Check bot latency
<help	<h, <ajuda	5s	List all commands
<avatar [@user]	<av	5s	Show user avatar
<userinfo [@user]	<ui, <user	5s	User info
<serverinfo	<si, <server	5s	Server info

Voice 🔒

Command	Alias	Cooldown	Description
<enter {name}	<e, <join	1s	Join voice channel
<getout	<go, <leave	1s	Leave voice channel

Music

Command	Alias	Cooldown	Description
<play {name/url}	<pl	3s	Play YouTube music
<pause	<pa	3s	Pause music
<resume	<re	3s	Resume music
<skip	<sk, <s	3s	Skip current song
<stop	<st	3s	Stop and clear queue
<loop	<l	3s	Toggle loop mode
<queue	<q, <fila	5s	Show queue
<nowplaying	<np	5s	Current song info

Moderation 🔒

Command	Alias	Cooldown	Description
<ban @user [reason]	<b	1s	Ban a member
<unban {id} [reason]	<ub	1s	Remove a ban by user ID
<clear {1-100}	<cl	1s	Delete messages
<blockchat	<bc	1s	Block current channel for the bot
<blockchat off	—	—	Unblock current channel
<blockchat list	—	—	List all blocked channels
<autorole @role	<ar	1s	Set auto-role for new members
<autorole off	—	—	Remove auto-role
<autorole	—	—	Show current auto-role
<memberlog #channel	<ml	1s	Enable member leave log in a channel
<memberlog off	—	—	Disable member log
<memberlog	—	—	Show current member log status
<welcome #channel	<wc	1s	Enable welcome messages
<welcome off	—	—	Disable welcome messages
<welcome	—	—	Show current welcome config

Rank & XP

Command	Alias	Cooldown	Description
<rank	<r, <xp	10s	Your level and XP
<rank [@user]	—	—	Another user's profile
<rank top	—	—	Server top 10

Utility

Command	Alias	Cooldown	Description
<remind {time} {msg}	<rm, <lembrete	30s	DM reminder
<coinflip	<cf, <moeda	3s	Flip a coin
<poll {question}	<votacao, <voto	10s	Create a poll
<botinfo	<bi, <info	10s	Bot technical info
<donate	<d, <apoiar	10s	Support the bot

🔒 Admin-only commands require the Administrator permission.

Additional resources

• 📄 VPS deployment guide

Main dependencies

Package	Purpose
discord.js	Discord API client
distube	Music playback engine
@distube/youtube	YouTube plugin for DisTube
@discordjs/voice	Voice channel connections
ffmpeg-static	Bundled FFmpeg binary
dotenv	Environment variable loader
typescript	TypeScript compiler
ts-node-dev	Development runner with hot reload

© 2026 Totalo — All rights reserved.

Project Status

• Status: in progress
• Phases: not defined
• Last checked: 18/06/2026