316 lines
12 KiB
Markdown
316 lines
12 KiB
Markdown
# 📝 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)
|
|
|
|
## 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."
|
|
}
|
|
```
|