Documentation

Welcome to the documentation of OpenQOTD! Here you can find all the information you need to get started with the bot, as well as some more advanced topics.

General Usage

You can interact with OpenQOTD using Slash Commands.
OpenQOTD also only acts once the configuration has been initialized, otherwise it does nothing.

Configuration

OpenQOTD must be configured initially using /config initialize.
Afterwards, /config set can be used to set config values (use /config reset to reset non-boolean optional values to their defaults), and /config get can be used to retrieve it.

/config can only be run by users with the "Administrator" server permission.

Variables

The following config variables can be set using /config initialize or /config set:
Required fields are marked with "field", and default values are shown using "value".

• basic_role: This is the role that is required to run non-administrative commands, which includes:
  • /suggest (if suggestions are enabled)
  • /leaderboard
  • /topic
  • /sentquestions
  This is set to everyone by default. That means, if this variable is unset, everyone in your server is able to run these commands.
  Do not try to set this to "@everyone", it will not work. Instead, reset it using /config reset basic_role if you want everyone to be able to run these commands.
• admin_role: This is the role that is required to run administrative and potentially destructive commands, which includes:
  • /questions
  • /presets
  • /trigger
  The "Administrator" server permission overrides this role, and anyone with this permission can run every command regardless of what roles they have.
  
• qotd_channel: This is the channel that QOTDs are sent to, which includes the daily QOTD and the QOTDs that are triggered manually using /trigger.
• qotd_time_hour_utc & qotd_time_minute_utc: The hour and minute at which the QOTDs are sent (if enable_automatic_qotd is enabled), in UTC time.
  The hour must be between 0 and 23, and the minute must be between 0 and 59.
  For example, if you want the QOTD to be sent at 3:47 PM UTC, you would set qotd_time_hour_utc to 15 and qotd_time_minute_utc to 47.
  You can use this tool to convert your local time to UTC, and keep in mind that it might change due to daylight saving time.
• qotd_day_condition: Can be used to specify on which days a QOTD should be sent. If unset, a QOTD gets sent every day.
  Note that this string must start with a percent sign (%) and is case-sensitive. The "epoch day" refers to the day that this config variable was last changed.
  The following formats are supported:
  • %D[n] (Every [n] days): Sends a QOTD every [n] days including the epoch day onwards. For example, %D2 sends a QOTD every other day.
  • %w{n} (On specific days of the week): Sends a QOTD on the specified days of the week, where {n} is a comma-separated list of day numbers starting with Monday as 1 (1 = Monday, 2 = Tuesday, 7 = Sunday, etc.). For example, %w1,3,5 sends a QOTD on Mondays, Wednesdays, and Fridays.
  • %W[n];[m] (Every [n] weeks on the [m]th day of the week): Sends a QOTD every [n] weeks on the specified day of the week, where [m] is the day of the week with Monday as 1 to Sunday as 7. For example, %W2;3 sends a QOTD every two weeks on Wednesdays.
  • %M{n} (On specific days of the month): Sends a QOTD on the specified days of the month, where {n} is a comma-separated list of day numbers (1-31). Note that if a month doesn't have the specified amount of days, then the last day of the month is chosen. For example, %M1,15,31 sends a QOTD on the 1st, the 15th, and on the last day of every month.
  Using /help, you can check when the next QOTD is scheduled to be sent.
• qotd_ping_role: This is the role that gets pinged when a QOTD is sent manually or using /trigger, even if it is a preset or there is no QOTD available.
  If this variable is unset, no role is pinged.
• qotd_titleQuestion Of The Day: The title that is displayed in QOTD messages.
  You can set this to display a different text, such as "Quote Of The Week" or "Topic Of The Month", allowing you to use the bot for whichever non-question purposes you want.
  This works great in combination with Profiles, to allow you to set up multiple instances of the bot, each with a different purpose.
• qotd_shorthandQOTD: An acronym or shortened form of the QOTD title that is used in various places, such as in button labels and command descriptions.
  Similar to qotd_title, you can set this to whatever you want, such as "QOTW" for "Quote Of The Week" or "TOTM" for "Topic Of The Month".
• enable_automatic_qotdtrue: If enabled, a QOTD is sent automatically every day at the set time.
  If this variable is set to false, the QOTD has to be triggered manually using /trigger.
• enable_qotd_pin_messagetrue: If enabled, the old QOTD, if existent and pinned, is unpinned and the new QOTD is pinned automatically after it is sent.
• enable_qotd_create_threadfalse: If enabled, a thread is created for the QOTD when it is sent, with the auto-archive duration being 24 hours.
• enable_qotd_automatic_presetstrue: If enabled, Presets are sent if there are no custom questions available.
  See Presets for more information.
• enable_qotd_last_available_warntrue: If enabled, a "Warning: Last QOTD" embed should be appended to a sent QOTD if it is the last available custom QOTD, advising users to make a suggestion if suggestions are enabled.
• enable_qotd_unavailable_messagetrue: If enabled, a message is sent if there are no QOTDs available, which happens if there are no custom questions available and presets are either disabled or exhausted.
  
• enable_qotd_show_info_buttontrue: If enabled, a little "𝐢"-button gets added under QOTDs.
  For non-admins and/or preset questions, it shows the output of /help; for normal questions if pressed by an admin, there is a prompt for whether to show /questions view for this question or /help.
  This is purely visual and for convenience, it does not alter any data, and the button responses only get shown to the person who pressed the button.
• enable_suggestionstrue: If enabled, users with the basic_role can suggest new questions using /suggest, /qotd or the suggest button under sent QOTDs.
  Suggested questions then have to be accepted by a staff member in order to be sendable. See Suggestions for more information.
• suggestions_channel: The channel where new suggestions are sent to, with buttons to accept/deny them.
  If this variable is unset, suggestions are not sent anywhere and can only be viewed using /suggestions.
  It is recommended to use this if you have suggestions enabled, as it makes them much easier to manage.
  See Suggestions for more information.
  ⚠️ Warning: Make sure to have this set to a channel that is only viewable by people you trust, as anyone can accept or deny suggestions using the buttons of the messages or /suggestions inside of that channel!
  
• suggestions_ping_role: The role that gets pinged alongside with the message in the suggestions_channel when a new suggestion is received.
  If this variable is unset, no role is pinged.
• notices_levelAll: Notices are messages that are sent alongside QOTDs, which are written by the developer and are used to inform users about updates, changes, suggestions and thelike.
  The following options are available:
  • All: All notices are sent. Keep in mind that some of these notices may include encouraging users to join the community server, donate, contribute, or similar, so keeping this enabled is appreciated in order to help this free and open-source project work out.
  • Important: Only important announcements are sent, including maintenance times and breaking changes. It is recommended to keep at least this level enabled.
  • None: No notices are sent whatsoever.
• enable_deleted_to_stashtrue: If enabled, when a suggestion gets denied or a question gets manually deleted, instead of being permanently deleted, its type will get set to Stashed unless it already is Stashed.
  Stashed questions can be cleared and thus be permanently deleted using /questions clearstash.
• logs_channel: The channel where logs are sent to, which includes changes being made to the config, questions or suggestions.
  ⚠️ Warning: This currently does not log the config getting re-initialized using /config initialize. I'm working to fix this in a future update, but for now, keep this in mind.

⚠️ Important: Make sure that, if set, the qotd_channel, suggestions_channel and logs_channel are channels that the bot has access to, can send messages with embeds in, and, if enabled, also pin messages, ping roles and manage threads in respectively.

Questions

Questions are the main feature of OpenQOTD, and they are what the bot sends every day.
They can be added by staff members or suggested by users (if suggestions are enabled). Presets work a little differently, to learn more about them see Presets.

A submittor can add the following information to a question when suggesting it:

• Contents (required): The main body of the question. Can be up to 2000 characters long.
• Additional Information (optional): If provided, a button will be available under the sent QOTD for users to ephemerally view this information. Can be up to 2000 characters long.
• Thumbnail Image URL (optional): If provided, this URL will be used as a thumbnail for the question. This does not check if the URL is valid, so make sure that this is a valid link starting with https://. Can be up to 256 characters long.
• Staff Info (optional): If provided, this information will get shown to staff members in the suggestion message or when viewed using the info button or /questions view. Can be up to 1000 characters long.

As an anti-spam measure, the total amount of questions (under all profiles combined) is limited to 65536. If a larger amount is needed, feel free to let me know personally and we'll figure something out.

Types

Each question has one of four types, Suggested, Accepted, Sent or Stashed:

• Suggested questions are those that have been suggested by users, and have to be accepted or denied by staff members in order to be sendable.
• Accepted questions are those that have been accepted or added by staff members, and are randomly chosen to be sent as QOTDs.
• Sent questions are those that have been sent already, and are not sendable again. Note that all questions of this type are publicly viewable to anyone with the basic_role using /sentquestions.
• Stashed questions are those that have either been deleted (if enable_deleted_to_stash is enabled) or manually set to Stashed.

As you can see, the only questions that are sendable are Accepted questions, and they are prioritized over Presets if they are available.
If a QOTD is triggered either automatically or using /trigger, a random Accepted question is sent, and that question is marked as Sent.

Commands

The following commands are available to manage questions and are only available to Administrators or users with the admin_role set in the config:
Required parameters are shown in square brackets ([required]) and optional in angled brackets (<required>), and default values are shown using "value".

• /questions view [question_id]: View all available information about a question, including its type, content, author, the date it was added, the person who accepted it, and more.
• /questions list <typeAll> <page1>: List all question of a certain type, which can be Suggested, Accepted or Sent.
• /questions search [query] <page1>: Search for questions using a query. All questions that contain the query in their content are shown, no matter the type. This is case-insensitive.
• /questions add [question] [type]: Add a question to the bot with a certain type, which can be Suggested, Accepted or Sent.
• /questions addbulk [questions_file] [type]: Add multiple questions from a file to the bot with a certain type, which can be Suggested, Accepted or Sent.
  The file must be a .txt file with each question on a new line. They are added in the order they are in the file, and as if added line-by-line using /questions add.
• /questions changetype [question_id] [type]: Change the type of a question to Suggested, Accepted or Sent. Note that setting a question from Suggest to Accepted works, but it is recommended to use /suggestions accept instead.
• /questions changetypebulk [from_type] [to_type]: Change the type of all questions of a certain type to another. For example, you can change all Sent questions to Accepted. Unlike /suggestions acceptall, running this command with Suggested→Accepted will not notify the suggesters.
• /questions remove [question_id]: Remove a question from. This will set the question type to Stashed if enable_deleted_to_stash is true and it's not already Stashed, otherwise it will permanently delete it.
• /questions removebulk [type]: Remove all questions of a certain type. If that type is Stashed or enable_deleted_to_stash is false, it will permanently delete all questions; otherwise, it will set the type to Stashed.
• /questions clearstash: Permanently delete all questions of type Stashed.

Suggestions

If suggestions are enabled (/config set enable_suggestions:True), users can suggest questions using /suggest or /qotd.
These suggestions (=questions with type Suggested) have to be accepted or denied by staff members in order to be sendable, and they are sent to the suggestions_channel with buttons to accept or deny them. The user is notified in DMs when their question is accepted/denied, including the denial reason if applicable.
If a suggestion is accepted, its type is changed to Accepted, and if it is denied, its type is changed to Stashed (or permanently deleted if enable_deleted_to_stash is false).
Note that anyone can accept or deny suggestions using the buttons of the messages or /suggestions in that channel, so make sure to have your suggestions_channel set to a channel that is only viewable by people you trust!

Commands

The following commands are available to manage suggestions and are only available to Administrators or users with the admin_role set in the config:
Required parameters are shown in square brackets ([required]) and optional in angled brackets (<required>), and default values are shown using "value".

• /suggestions accept [suggestion_id]: Accepts a suggestion. This changes the type of the question to Accepted and notifies the suggester in private messages.
• /suggestions deny [suggestion_id] [reason]: Denies a suggestion with a reason. This sets the question type to Stashed (or permanently deletes it if enable_deleted_to_stash is true) and notifies the suggester with the denial reason in private messages.
  
• /suggestions acceptall: Accepts all suggestions. This changes the type of all suggestions to Accepted and notifies the suggesters in private messages.
• /suggestions denyall: Denies all suggestions without reason. This stashes/deletes all suggestions from the bot and notifies the suggesters in private messages.
  

Note that if you want to list all suggestions, you can use /questions list type:Suggested.

Presets

Presets are a special type of questions that are sent if they are enabled (/config set enable_qotd_automatic_presets:True) and there are no custom questions available.
Once a preset is sent, it is marked as completed, and is not sendable unless it is manually enabled again. They do NOT show in the /questions or /suggestions listings, and they are not editable, however it is possible to disable them individually by manually marking them as completed using /presets setactive.
Just like questions, they get sent in a random order and not as a queue.

Commands

• /presets list <type> <page1>: List all presets of a certain type, which can be Active or Completed.
  If no type is specified, all presets are shown.
• /presets setactive [preset_id] [active]: Set a preset to be Active or Completed. If a preset is active, it is sent if there are no custom questions available.
  
• /presets reset: Reset all presets to be active. This makes all presets sendable if there are no custom questions available.
• /presets suggest: Suggest a preset to be added to the bot globally. If you have any good ideas for preset questions, feel free to suggest them using this command!

Other Commands

The following commands are other commands, most of which are available to everyone with the basic_role role (with a notable exception being /trigger which is admin-only):
Required parameters are shown in square brackets ([required]) and optional in angled brackets (<required>), and default values are shown using "value".

• /help: Print general information about the bot, including some useful information about the config.
• /leaderboard [of] <page1>: View the leaderboard of a certain profile, which shows the top users by the amount of Sent questions they have added (questions that have been accepted and sent as QOTD).
  This is the same as /lb.
• /topic [from] <include_presetstrue>: Send a random question from a certain profile of type Sent to the current channel.
  If include_presets is set to true and presets are enabled in the config (check with /help), presets are also included in the random selection.
  This can be used to revive a dead chat and find an interesting topic to talk about.
  Using a button below the message, the person who ran the command can reroll the question as many times as they want.
  This command is purely visual, and does not alter the questions in any way, and the same topic can be sent multiple times.
• /sentquestions <page1>: List all questions that have been sent as QOTD.
  This is the same as /questions list type:Sent, except that it is available to all users with the basic_role (not just admins).
• /qotd: Opens up the QOTD suggestion modal for the default profile.
  /suggest [for] is essentially the same, but allows users to specify any profile where they have suggestion permission.
• /trigger: Trigger a QOTD manually. This sends a random available QOTD, as if it was sent automatically. This also prevents a second QOTD from being sent automatically at the same day and recalculates the QOTD schedule.
  This command is only available to Administrators or users with the admin_role set in the config.
• /feedback [message]: Send feedback to the bot's developer.
  This is available to all users globally, even if they don't have the basic_role.

Profiles

Profiles are an advanced feature that allows you to set up multiple instances of OpenQOTD in a single server, each with its own configuration, questions, presets, and suggestions. This is useful if you want to have different QOTD setups for different purposes, such as having one for daily questions and another for weekly quotes.
This feature is designed to be as usable as possible for both admins and regular users, while still acknowledging the increased complexity that comes with it. You also don't need to deal with it if you only use the bot for a single purpose.
/profiles can be used to manage and switch between profiles, and note that only users with the "Administrator" server permission can remove and create profiles, however anyone can switch to a profile they have the admin_role for.
Any admin-command except for /profiles will only refer to the currently selected profile. For example, if you use /questions add, it will add the question to the currently selected profile; if you haven't selected any profile yet, it will use the default profile. Basic commands will instead include a dropdown to select the profile.
Profiles are more or less equivalent to initialized configs (internally, profiles are merely syntactic sugar to allow people to manage multiple configs within a single server). The config variable profile_name is used to identify the profile for admins.
Users can view basic informations and run basic commands for all profiles they have the basic_role in, and suggest questions for them if suggestions are enabled. For basic commands, the qotd_title config variable is used to identify the profile, and only profiles that meet these criteria are shown in the dropdown to users in commands like /suggest [for].
Note that as an anti-spam measure, the total amount of profiles in a server is limited to 64.

Commands

• /profiles new: This lets you enter new-profile-mode. This command is only available to users with the "Administrator" server permission.
  The command itself does not create a new profile immediately, but after running it, /config initialize will let you initialize a new config independently of the existing ones. Once this is done, the new profile is created. While not a requirement, it is recommended to set the profile_name, qotd_title and qotd_shorthand config variables to avoid confusion and ambiguity for admins and members, and to disable enable_qotd_automatic_presets and to set notices_level to None.
• /profiles list: List all viewable profiles in the server.
  For users with the "Administrator" server permission, all profiles are shown; for other users, only profiles where they have the basic_role are shown. The currently selected profile is indicated with a "☑️" symbol. Profiles that a user can switch to, i.e. profiles where they have the admin_role, are shown with a "◻️" symbol, while those that are merely viewable are shown using "▪️".
• /profiles switchto [profile]: Switch to a different profile.
  Here, the profile names of the switchable profiles are shown. A user can only switch to profiles where they have the admin_role in.
  Once switched, all subsequent admin-commands that this user runs will refer to the selected profile until another profile is selected.
• /profiles delete: Delete the currently selected profile. This command is only available to users with the "Administrator" server permission.
  Deleting a profile will permanently remove all its configuration, questions, presets, and suggestions. This action is irreversible.
  The default profile cannot be deleted, and may instead be re-assigned using /profiles setdefault before deleting the current default profile.
• /profiles setdefault: Mark the currently selected profile as the global default profile. This command is only available to users with the "Administrator" server permission.
  The default profile is the one that is used for /qotd and for admin commands when a user has not selected any profile yet, and it cannot be deleted unless another profile is set as default first.

Self-Hosting

OpenQOTD is open-source and can be self-hosted! If you want to run your own instance of the bot, you can find the source code on GitHub. Follow the instructions in the README to set it up, and let me know if there are any issues and I'm happy to help. Note that for versions v2.0.0 onward, the AGPL-3.0 License requires you to publish the source code of your instance (or provide a link to the OpenQOTD repository if you didn't make any modifications) if your instance is publicly accessible (i.e. if other people can add your bot to their servers or if you're using it in a public server).