Quick Example

Now after setting up our environment, we can start building a basic bot.

import mizuki

bot = mizuki.Bot(
    intents=mizuki.IntentFlags.standard()
)

@bot.setup()
async def setup():
    commands = await bot.commands.sync_all()
    print(f"Synced {len(commands)} commands!")

@bot.command(
    name="ping",
    description="Pings the bot!"
)
async def ping(interaction: mizuki.Interaction):
    await interaction.response.send_response("Pong!")

bot.run("TOKEN-HERE")

There’s a lot of things going on here, so let’s walk through it.

The first line just imports the library.

import mizuki

Next up we create an instance of a Bot with mizuki.Bot with the parameter intents. mizuki.IntentFlags define the events which your bot gets from Discord. Here we use mizuki.IntentFlags.standard() to enable all non-privileged intents. You can learn more about intents here.

bot = mizuki.Bot(
    intents=mizuki.IntentFlags.standard()
)

We use the @Bot.setup() decorator to make a setup hook. This function will run right alongside the connection of the gateway.

Here we call the bot.commands.sync_all() method to sync all of our commands registered with @Bot.command to Discord. The method here also returns a list of the Application Commands we just synced.

@bot.setup()
async def setup():
    commands = await bot.commands.sync_all()
    print(f"Synced {len(commands)} commands!")

Note

The gateway connection is not guaranteed to be ready in this function! Look to @Bot.listen() with the Event.READY for that.

We use the @Bot.command() decorator with the name and description parameters to define how the command will appear in Discord.

The method we apply the decorator to is our “callback” function, it will be executed when someone uses the command in Discord.

Every command callback receives an Interaction as its first parameter. If the callback is defined within a class, self is passed first and the Interaction becomes the second parameter.

interaction.response is our ResponseHandler, which we will be using to send, followup, edit and delete our responses. ResponseHandler.send_response() is used to send the first intial response to the command.

@bot.command(
    name="ping",
    description="Pings the bot!"
)
async def ping(interaction: mizuki.Interaction):
    await interaction.response.send_response("Pong!")

Important

All application commands must be responded or deferred to in under 3 seconds. If an interaction is not responded or deferred, then the interaction is invalidated.

After acknowledging the interaction, you can keep responding with ResponseHandler.send_followup() until the interaction token is invalidated in 15 minutes.

Finally, we run the bot using Bot.run() with the token parameter.

bot.run("TOKEN-HERE")

Important

You should never hardcode your tokens in a production bot or commit them to version control. See the next section for recommended approaches.

You have made your first Discord bot! You can run it by activating your venv and running the python file.

Protecting your Tokens

While putting your tokens directly into the code is simple, it is not the recommended way to store sensitive info like passwords and token. For this guide, we will be using python-dotenv.

First start by adding python-dotenv to your dependencies and install it.

uv

uv add python-dotenv

venv

Activate your Virtual Environment as shown in Managing Virtual Environments.

pip install python-dotenv

After installing the package, make a file named .env and put yout token in the .env file like:

.env

DISCORD_TOKEN=TWl6dWVuYUlzUGVha1l1cmlXZUxvdmVNaXp1RW5h

Note

DISCORD_TOKEN is just a variable name and it can be named anything. Replace the TWl….W5h with your own bot’s token.

Inside your code you can now get the token by doing:

import os
from dotenv import load_dotenv

load_dotenv()

TOKEN = os.getenv("DISCORD_TOKEN")

Important

If you are using git to track your project, create a file named .gitignore in the root of your project (alongside .env) and add the following:

.gitignore

.env

This prevents the .env file from being tracked by git, helping ensure that sensitive information such as your bot token is not accidentally committed.