Project Guide: Bot

 GitHub Repo  Documentation


You'll need these to be set up before you can do any work on the bot:

Creating a Discord Application

First, ensure you have a guild available for testing to which you can invite your bot. If not, simply create one.

Go to the Discord Developer Portal and click "Create an Application". Click on the "Bot" tab on the left, then click "Add Bot" (confirm when prompted). Here there will be a button to copy your token. You will later need to return here to get this token. You will also find a switch to make the bot private instead of public, which you may want to do.

Next, click on the "OAuth2" tab on the left. Scroll down to the URL generator and select the "Bot" checkbox. Below that, select the "Administrator" permission for the bot. Now you can copy the generated URL and open it. Once opened, you will be able to select a server to which to invite your bot.

Setting up

Head over to the GitHub repo, and click on the "Fork" button to create a copy of the repository under your account.

Open a terminal (or Git Bash on Windows) and run the following, replacing YOUR USERNAME with your GitHub username:

git clone

This will download a copy of the repository, ready for you to work on. Next, change directory into the repository folder and use Pipenv to install a virtualenv with all of the project requirements and tools:

cd bot/
pipenv sync --dev


Make a copy of config-default.yml, name it config.yml, and open it for editing.

Configure the rabbitmq section. Unless you configured the credentials or the port, the following defaults should work:

    host:          "localhost"
    password:      "guest"
    port:          5672
    username:      "guest"

If you aren't hosting the site on the same machine, change the host accordingly. For example, if you are on Windows and you had to change the RABBITMQ_HOST environment variable when you set up site, you need to change the value of host here to match the value of that environment variable.

Next, configure site (under urls) to whatever base URL you put in your hosts file when setting up the site. Nearby, set site_schema to http://. If you used the hosts from the site project guide, the start of this section should end up configured like this:

    # PyDis site vars
    site:        &DOMAIN       "pythondiscord.local:8080"
    site_api:    &API    !JOIN ["api.", *DOMAIN]
    site_paste:  &PASTE  !JOIN ["paste.", *DOMAIN]
    site_schema: &SCHEMA       "http://"

Lastly, configure the role and channel IDs under guild. These should be set the IDs of the equivalent channels and roles on your test guild. You could probably re-use the same role or channel ID to configure many of these, but this will depenend on what you plan on working on or testing. To get an ID, go on Discord and add a backslash before you type a mention for a role or channel:



The ID is between the angle brackets. The @& or # are not part of the ID.

Environment Variables

Two environment variables need to be set:

  • BOT_API_KEY - should be set to the same value as the one set for the site

  • BOT_TOKEN - the token for the bot account you created earlier

If you plan to run the bot from command line with pipenv, create a file named .env at the project root and set the environment variables inside like so:


If instead you plan to run the bot from an IDE, look into your IDE's run configuration to set the above environment variables.

Working with the code

Make your changes in your favourite editor or IDE, and make sure you test your code. You can run a linter over the Python code and start the server with:

pipenv run lint  # Check the code for styling errors
pipenv run start  # Run the bot