A simple Discord bot for taking and reporting attendance of users within a specific voice channel.

Originally created for Boring Security DAO.

1. Git - Install Git
   1. Check if you have Git installed with git --version
2. Python (>=3.10; <4) - Install Python (Windows), Install Python (Linux)
   1. Check if you have Python installed with python3 --version
3. Pip - Install Pip
   1. Check if you have Pip installed with pip --version
4. Poetry - Install Poetry (preferrably with pipx)
   1. Check if you have Poetry installed with poetry --version
5. Docker - Install Docker (optionally)
   1. Check if you have Docker installed with docker --version

This repo assumes you understand how to create an application through the Discord Dev Portal and attach a bot to it. It is recommended to set the bot to private (public bot: off), as the bot is designed to be self-hosted and only interact with a single guild (server).

The bot requires no intents or specific permissions when inviting it; Send Messages is only temporarily required, globally, during bot setup. If the voice channel(s) you intend to use with the bot require a specific role or are otherwise restricted in some way, you need to grant an explicit View Channel permission to the bot for that voice channel. Otherwise, the bot is able to view all voice channels the @everyone role can view. To generate a bot invite link, go to your bot's application page in the Discord Dev Portal, then navigate to OAuth2 -> URL Generator. Select the bot and applications.commands scopes; no permissions are required (see suggested permissions below).

git clone https://github.com/vile/discord-attendance-bot.git && cd discord-attendance-bot

mv .env.example .env

Put your bot's token in .env as DISCORD_BOT_TOKEN. Put your guild's ID in .env as GUILD_ID.

This will create a venv and install the required dependencies with Poetry then immediately start the bot.

make

make deps

make start

To make application commands available in the server, mention the bot to invoke the sync text command. Where ~ syncs all guild commands to the current guild (see: command body, archive). Make sure the bot, temporarily, has Send Messages in the channel where you are mentioning the bot.

<@BOT_USER_ID> sync ~

If application commands are not synced to the guild, the bot integration will show that "this application has no commands," (rendering all commands unusable) and autocomplete will not work.

After the command tree has been synced, the bot no longer requires the global Send Messages permission.

It might be necessary to prefix commands with sudo when using docker compose commands. Use the .env file as normal (include your DISCORD_BOT_TOKEN and GUILD_ID), it is included in the compose.

Compose the docker image from the Dockerfile and start a new container. Optionally pass the -d flag to start the container in the background. When using make commands, pass all desired flags under FLAGS (e.g., FLAGS='-d'). All make docker* targets support FLAGS.

make dockerup-build

OR

docker compose up --build --remove-orphans

Stop the container (gracefully) with CTRL+C when not using the -d flag.

Restart an already created container with the following command (don't rebuild).

make dockerup

OR

docker compose up

Stop a background container (started with the -d flag).

docker compose stop

Stop the container and/or delete the Docker image.

make dockerdown

OR

docker compose down --remove-orphans

Composing down will delete the current container and remove persistent data used by the bot, such as settings (snapshot interval, attendance rate) and snapshot data. However, due to the low setup complexity of the bot (and that snapshot data is cleared on each bot start anyways), using a volume to persist this data does not make sense for the small gain.

docker compose ps

docker compose images

Since this bot is developed using Python's shelve module for persistent data storage, there are some limitations intentionally imposed. Specifically, the retention of attendance session data (snapshots). Snapshot data is permanently cleared when using the /attendance clear command, as well as on each bot start. As such, instructors using this bot should immediately export an attendance report using the /attendance get command.

• The discord.py Discord and mod team for answering my questions
• AbstractUmbra's open source command tree syncing command (The Unlicense)