diff options
Diffstat (limited to 'docs/configuration.md')
| -rw-r--r-- | docs/configuration.md | 342 |
1 files changed, 342 insertions, 0 deletions
diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..cb4f2bb --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,342 @@ +# 📝 Configuration +Haven't set up the bot yet? Check out [Setting up the bot](setup.md) first! + +## Table of contents +- [Configuration file](#configuration-file) (start here) +- [Adding new options](#adding-new-options) +- [Required options](#required-options) +- [Other options](#other-options) +- [config.ini vs config.json](#configini-vs-configjson) +- [Other formats](#other-formats) +- [Environment variables](#environment-variables) + +## Configuration file +All bot options are saved in a configuration file in the bot's folder. +This is created during the [setup](setup.md) and is generally either `config.ini` or, if you've been using the bot for +longer, `config.json`. + +The instructions on this page are for `config.ini` but can be adapted to `config.json` as well. +See [config.ini vs config.json](#configini-vs-configjson) for more details. +Note that the format of `.ini` and `.json` are different -- you can't simply rename a `.json` to `.ini` or +vice versa. + +## Adding new options +To add a new option to your `config.ini`, open the file in a text editor such as notepad. +Each option is put on a new line, and follows the format `option = value`. For example, `mainGuildId = 1234`. + +**You need to restart the bot for configuration changes to take effect!** + +You can add comments in the config file by prefixing the line with `#`. Example: +```ini +# This is a comment +option = value +``` + +### Toggle options +Some options like `allowMove` are "**Toggle options**": they control whether certain features are enabled (on) or not (off). +* To enable a toggle option, set its value to `on`, `true`, or `1` +* To disable a toggle option, set its value to `off`, `false`, or `0` +* E.g. `allowMove = on` or `allowMove = off` + +### "Accepts multiple values" +Some options are marked as "**Accepts multiple values**". To give these options multiple values, +write the option as `option[] = value` and repeat for every value. For example: + +```ini +inboxServerPermission[] = kickMembers +inboxServerPermission[] = manageMessages +``` + +You can also give these options a single value in the usual way, i.e. `inboxServerPermission = kickMembers` + +### Multiple lines of text +For some options, such as `greetingMessage`, you might want to add text that spans multiple lines. +To do that, use the same format as with "Accepts multiple values" above: + +```ini +greetingMessage[] = Welcome to the server! +greetingMessage[] = This is the second line of the greeting. +greetingMessage[] = +greetingMessage[] = Fourth line! With an empty line in the middle. +``` + +## Required options + +#### token +The bot user's token from [Discord Developer Portal](https://discordapp.com/developers/). + +#### mainGuildId +Your server's ID, wrapped in quotes. + +#### mailGuildId +For a two-server setup, the inbox server's ID. +For a single-server setup, same as [mainGuildId](#mainguildid). + +#### logChannelId +ID of a channel on the inbox server where logs are posted after a modmail thread is closed + +## Other options + +#### accountAgeDeniedMessage +**Default:** `Your Discord account is not old enough to contact modmail.` +See `requiredAccountAge` below + +#### allowMove +**Default:** `off` +If enabled, allows you to move threads between categories using `!move <category>` + +#### allowUserClose +**Default:** `off` +If enabled, users can use the close command to close threads by themselves from their DMs with the bot + +#### alwaysReply +**Default:** `off` +If enabled, all messages in modmail threads will be sent to the user without having to use `!r`. +To send internal messages in the thread when this option is enabled, prefix them with `!note` (using your `prefix`), +e.g. `!note This is an internal message`. + +#### alwaysReplyAnon +**Default:** `off` +If `alwaysReply` is enabled, this option controls whether the auto-reply is anonymous + +#### attachmentStorage +**Default:** `local` +Controls how attachments in modmail threads are stored. Possible values: +* **local** - Files are saved locally on the machine running the bot +* **discord** - Files are saved as attachments on a special channel on the inbox server. Requires `attachmentStorageChannelId` to be set. + +#### attachmentStorageChannelId +**Default:** *None* +When using attachmentStorage is set to "discord", the id of the channel on the inbox server where attachments are saved + +#### botMentionResponse +**Default:** *None* +If set, the bot auto-replies to bot mentions (pings) with this message. Use `{userMention}` in the text to ping the user back. + +#### categoryAutomation.newThread +**Default:** *None* +ID of the category where new threads are opened. Also functions as a fallback for `categoryAutomation.newThreadFromGuild`. + +#### categoryAutomation.newThreadFromGuild.GUILDID +**Default:** *None* +When running the bot on multiple main servers, this allows you to specify new thread categories for users from each guild. Example: +```ini +# When the user is from the server ID 94882524378968064, their modmail thread will be placed in the category ID 360863035130249235 +categoryAutomation.newThreadFromGuild.94882524378968064 = 360863035130249235 +# When the user is from the server ID 541484311354933258, their modmail thread will be placed in the category ID 542780020972716042 +categoryAutomation.newThreadFromGuild.541484311354933258 = 542780020972716042 +``` + +#### closeMessage +**Default:** *None* +If set, the bot sends this message to the user when the modmail thread is closed. + +#### commandAliases +**Default:** *None* +Custom aliases/shortcuts for commands. Example: +```ini +# !mv is an alias/shortcut for !move +commandAliases.mv = move +# !x is an alias/shortcut for !close +commandAliases.x = close +``` + +#### enableGreeting +**Default:** `off` +When enabled, the bot will send a greeting DM to users that join the main server. + +#### greetingAttachment +**Default:** *None* +Path to an image or other attachment to send as a greeting. Requires `enableGreeting` to be enabled. + +#### greetingMessage +**Default:** *None* +Message to send as a greeting. Requires `enableGreeting` to be enabled. Example: +```ini +greetingMessage[] = Welcome to the server! +greetingMessage[] = Remember to read the rules. +``` + +#### guildGreetings +**Default:** *None* +When running the bot on multiple main servers, this allows you to set different greetings for each server. Example: +```ini +guildGreetings.94882524378968064.message = Welcome to server ID 94882524378968064! +guildGreetings.94882524378968064.attachment = greeting.png + +guildGreetings.541484311354933258.message[] = Welcome to server ID 541484311354933258! +guildGreetings.541484311354933258.message[] = Second line of the greeting. +``` + +#### ignoreAccidentalThreads +**Default:** `off` +If enabled, the bot attempts to ignore common "accidental" messages that would start a new thread, such as "ok", "thanks", etc. + +#### inboxServerPermission +**Default:** *None* +**Accepts multiple values.** Permission name, user id, or role id required to use bot commands on the inbox server. +See ["Permissions" on this page](https://abal.moe/Eris/docs/reference) for supported permission names (e.g. `kickMembers`). + +#### timeOnServerDeniedMessage +**Default:** `You haven't been a member of the server for long enough to contact modmail.` +If `requiredTimeOnServer` is set, users that are too new will be sent this message if they try to message modmail. + +#### mentionRole +**Default:** `here` +**Accepts multiple values.** Role that is mentioned when new threads are created or the bot is mentioned. +Accepted values are "here", "everyone", or a role id. +Requires `pingOnBotMention` to be enabled. +Set to an empty value (`mentionRole=`) to disable these pings entirely. + +#### mentionUserInThreadHeader +**Default:** `off` +If enabled, mentions the user messaging modmail in the modmail thread's header. + +#### newThreadCategoryId +**Default:** *None* +**Deprecated.** Same as `categoryAutomation.newThread`. + +#### pingOnBotMention +**Default:** `on` +If enabled, the bot will mention staff (see `mentionRole` option) on the inbox server when the bot is mentioned on the main server. + +#### plugins +**Default:** *None* +**Accepts multiple values.** External plugins to load on startup. See [Plugins](plugins.md) for more information. + +#### port +**Default:** `8890` +Port to use for attachments (when `attachmentStorage` is set to `local`) and logs. +Make sure to do the necessary [port forwarding](https://portforward.com/) and add any needed firewall exceptions so the port is accessible from the internet. + +#### prefix +**Default:** `!` +Prefix for bot commands + +#### relaySmallAttachmentsAsAttachments +**Default:** `off` +If enabled, small attachments from users are sent as real attachments rather than links in modmail threads. +The limit for "small" is 2MB by default; you can change this with the `smallAttachmentLimit` option. + +#### requiredAccountAge +**Default:** *None* +Required account age for contacting modmail (in hours). If the account is not old enough, a new thread will not be created and the bot will reply with `accountAgeDeniedMessage` (if set) instead. + +#### requiredTimeOnServer +**Default:** *None* +Required amount of time (in minutes) the user must be a member of the server before being able to contact modmail. If the user hasn't been a member of the server for the specified time, a new thread will not be created and the bot will reply with `timeOnServerDeniedMessage` (if set) instead. + +#### responseMessage +**Default:** `Thank you for your message! Our mod team will reply to you here as soon as possible.` +The bot's response to the user when they message the bot and open a new modmail thread + +#### rolesInThreadHeader +**Default:** `off` +If enabled, the user's roles will be shown in the modmail thread header + +#### smallAttachmentLimit +**Default:** `2097152` +Size limit of `relaySmallAttachmentsAsAttachments` in bytes (default is 2MB) + +#### snippetPrefix +**Default:** `!!` +Prefix for snippets + +#### snippetPrefixAnon +**Default:** `!!!` +Prefix to use snippets anonymously + +#### status +**Default:** `Message me for help` +The bot's "Playing" text + +#### syncPermissionsOnMove +**Default:** `on` +If enabled, channel permissions for the thread are synchronized with the category when using `!move`. Requires `allowMove` to be enabled. + +#### threadTimestamps +**Default:** `off` +If enabled, modmail threads will show accurate UTC timestamps for each message, in addition to Discord's own timestamps. +Logs show these always, regardless of this setting. + +#### typingProxy +**Default:** `off` +If enabled, any time a user is typing to modmail in their DMs, the modmail thread will show the bot as "typing" + +#### typingProxyReverse +**Default:** `off` +If enabled, any time a moderator is typing in a modmail thread, the user will see the bot "typing" in their DMs + +#### updateNotifications +**Default:** `on` +If enabled, the bot will automatically check for new bot updates periodically and notify about them at the top of new modmail threads + +#### url +**Default:** *None* +URL to use for attachment and log links. Defaults to `http://IP:PORT`. + +#### useNicknames +**Default:** `off` +If enabled, mod replies will use their nicknames (on the inbox server) instead of their usernames + +## config.ini vs config.json +Earlier versions of the bot instructed you to create a `config.json` instead of a `config.ini`. +**This is still fully supported, and will be in the future as well.** +However, there are some differences between `config.ini` and `config.json`. + +### Formatting +*See [the example on the Wikipedia page for JSON](https://en.wikipedia.org/wiki/JSON#Example) +for a general overview of the JSON format.* + +* In `config.json`, all text values and IDs need to be wrapped in quotes, e.g. `"mainGuildId": "94882524378968064"` +* In `config.json`, all numbers (other than IDs) are written without quotes, e.g. `"port": 3000` + +### Toggle options +In `config.json`, valid values for toggle options are `true` and `false` (not quoted), +which correspond to `on` and `off` in `config.ini`. + +### "Accepts multiple values" +Multiple values are specified in `config.json` using arrays: +```json +{ + "inboxPermission": [ + "kickMembers", + "manageMessages" + ] +} +``` + +### Multiple lines of text +Since `config.json` is parsed using [JSON5](https://json5.org/), multiple lines of text are supported +by escaping the newline with a backslash (`\ `): +```json5 +{ + "greetingMessage": "Welcome to the server!\ +This is the second line of the greeting." +} +``` + +## Other formats +Loading config values programmatically is also supported. +Create a `config.js` in the bot's folder and export the config object with `module.exports`. +All other configuration files take precedence, so make sure you don't have both. + +## Environment variables +Config options can be passed via environment variables. + +To get the name of the corresponding environment variable for an option, convert the option to SNAKE_CASE with periods +being replaced by two underscores and add `MM_` as a prefix. If adding multiple values for the same option, separate the +values with two pipe characters: `||`. + +Examples: +* `mainGuildId` -> `MM_MAIN_GUILD_ID` +* `commandAliases.mv` -> `MM_COMMAND_ALIASES__MV` +* From: + ```ini + inboxServerPermission[] = kickMembers + inboxServerPermission[] = manageMessages + ``` + To: + `MM_INBOX_SERVER_PERMISSION=kickMembers||manageMessages` + +The `port` option also accepts the environment variable `PORT` without a prefix, but `MM_PORT` takes precedence. |