Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/DJERLO/Simple-Discord-Music-Bot-Using-Nextcord/llms.txt

Use this file to discover all available pages before exploring further.

Before the bot can join a voice channel and play music, you need a registered Discord application with a bot token, the correct gateway intents enabled, and an invite link scoped to the right permissions. This guide walks through each step in the Discord Developer Portal and then shows exactly what happens when bot.py starts up.
Your bot token is equivalent to a password. Never share it, commit it to version control, or paste it in a public channel. Store it exclusively in a .env file that is listed in .gitignore. If a token is ever exposed, immediately regenerate it in the Developer Portal.

​
Creating a Discord Application

1

Open the Developer Portal

Navigate to https://discord.com/developers/applications and sign in with your Discord account.
2

Create a new application

Click New Application in the top-right corner. Give it a name — this becomes the default bot username — then click Create.
3

Add a bot user

In the left sidebar, open the Bot tab. Click Add Bot and confirm. Discord creates a bot user attached to your application.
4

Copy your bot token

Under the Token section, click Reset Token, confirm the action, then copy the token that appears. This is your BOT_TOKEN.Paste it into a .env file in the project root:
.env
BOT_TOKEN=your_token_here
The bot loads this value at startup via python-dotenv:
bot.py
load_dotenv()
bot_token = os.getenv('BOT_TOKEN')
5

Enable Message Content Intent

Still on the Bot tab, scroll down to Privileged Gateway Intents. Enable Message Content Intent.The bot code explicitly requests this intent:
bot.py
intents = nextcord.Intents.default()
intents.message_content = True  # Enables the message content intent
Without this toggle enabled in the portal, Nextcord will not receive message content events even if the intent is declared in code.

​
Setting Bot Permissions

When inviting the bot to a server you must grant it the permissions it needs to function. The table below lists every required permission and why it is needed.
PermissionCategoryReason
ConnectVoiceJoin voice channels to stream audio
SpeakVoiceTransmit audio through the voice connection
Send MessagesTextPost now-playing embeds and command responses
Embed LinksTextRender rich embeds with artwork and track details
Read Message HistoryTextAllow the bot to edit its own persistent player message

​
Generating an Invite URL

1

Open the OAuth2 URL Generator

In the Developer Portal, navigate to OAuth2 → URL Generator in the left sidebar.
2

Select scopes

Under Scopes, check both:
  • bot
  • applications.commands
The applications.commands scope is required for Discord to register and display the slash commands that the bot syncs via bot.sync_application_commands().
3

Select bot permissions

The Bot Permissions panel appears once bot is checked. Enable:
  • Connect
  • Speak
  • Send Messages
  • Embed Links
  • Read Message History
4

Copy and open the generated URL

Copy the URL at the bottom of the page, paste it into a browser, select the server you want to invite the bot to, and click Authorise.
Create a dedicated Discord server purely for development and testing. This gives you a safe environment to invite the bot, trigger commands, and observe its behaviour without affecting a live community server.

​
Running the Bot

With Lavalink running (see Lavalink Setup) and the .env file in place, start the bot: 
python bot.py

​
What happens at startup

The on_ready event fires once the bot has authenticated with Discord’s gateway. It performs three tasks in sequence:
bot.py
@bot.event
async def on_ready():
    """Connect to Lavalink node (defined in application.yml) when the bot is ready"""
    node: wavelink.Node = wavelink.Node(uri="http://127.0.0.1:2333", password="youshallnotpass")
    await wavelink.Pool.connect(nodes=[node], client=bot)
    await bot.sync_application_commands()
  1. Connects to Lavalink — creates a wavelink.Node pointed at http://127.0.0.1:2333 using the password defined in application.yml (youshallnotpass).
  2. Registers the node pool — wavelink.Pool.connect makes the node available for all subsequent voice connections.
  3. Syncs slash commands — bot.sync_application_commands() registers all @bot.slash_command decorators with Discord’s API.
Global slash command registration can take up to an hour to propagate to all servers. During development, commands usually appear much faster — typically within a few minutes of the bot connecting.

​
Configuration Reference

ValueWherePurpose
BOT_TOKEN.envAuthenticates the bot with Discord’s gateway
http://127.0.0.1:2333bot.py on_readyLavalink node URI
youshallnotpassbot.py on_readyLavalink node password (must match application.yml)

Build docs developers (and LLMs) love

Get started for freeTalk to us