Discord Attendance Bot

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

Originally created for Boring Security DAO.

Requirements

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

Usage

Creating a Discord Bot (App)

Creating an application

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).

Disable Public Bot

Invite the bot

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).

Required Scopes

Suggested Permissions

Invite Link Example

• https://discord.com/api/oauth2/authorize?client_id=YOUR_BOT_ID&permissions=3072&scope=bot+applications.commands

Installing

Clone this repo

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

Rename example .env file

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.

Quick Start

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

make

Normal Start

Create venv and install dependencies with Poetry

make deps

Start the bot

make start

Sync Commands to Guild

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.

This application has no commands

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

Properly synced commands

Using the bot with Docker

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.

Caution

Composed images should NOT be shared or uploaded to public repos/hubs, your bot's token is included in the image environment variables.

Compose up and start

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

Compose down

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.

View running containers

docker compose ps

View images

docker compose images

Known Limitations

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.

Acknowledgements

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