# 📝 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, `mainServerId = 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 ``` ### Toggled options Some options like `allowMove` can only be turned on or off. * To turn on a toggled option, set its value to `on`, `true`, or `1` * To turn off a toggled 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/). #### mainServerId **Accepts multiple values** Your server's ID. #### inboxServerId For a single-server setup, same as [mainServerId](#mainServerId). For a two-server setup, the inbox server's ID. #### 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 ` #### allowUserClose **Default:** `off` If enabled, users can use the close command to close threads by themselves from their DMs with the bot #### allowStaffDelete **Default:** `on` If enabled, staff members can delete their own replies in modmail threads with `!delete` #### allowStaffEdit **Default:** `on` If enabled, staff members can edit their own replies in modmail threads with `!edit` #### 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 #### anonymizeChannelName **Default:** `off` If enabled, channel names will be the user's name and discriminator salted with the current time, then hashed to protect the user's privacy #### attachmentStorage **Default:** `original` Controls how attachments in modmail threads are stored. Possible values: * `original` - The original attachment is linked directly * `local` - Files are saved locally on the machine running the bot and served via a local web server * `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.newThreadFromServer`. #### categoryAutomation.newThreadFromGuild.SERVER_ID Alias for [`categoryAutomation.newThreadFromServer`](#categoryAutomationNewThreadFromServerServer_id) #### categoryAutomation.newThreadFromServer.SERVER_ID **Default:** *None* When running the bot on multiple main servers, this allows you to specify which category to use for modmail threads from each server. Example: ```ini # When the user is from the server ID 94882524378968064, their modmail thread will be placed in the category ID 360863035130249235 categoryAutomation.newThreadFromServer.94882524378968064 = 360863035130249235 # When the user is from the server ID 541484311354933258, their modmail thread will be placed in the category ID 542780020972716042 categoryAutomation.newThreadFromServer.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 Alias for [`serverGreetings`](#serverGreetings) #### 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. #### mainGuildId Alias for [mainServerId](#mainServerId) #### mailGuildId Alias for [inboxServerId](#inboxServerId) #### 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`. #### notifyOnMainServerJoin **Default:** `on` If enabled, a system message will be posted into any open threads if the user joins a main server #### notifyOnMainServerLeave **Default:** `on` If enabled, a system message will be posted into any open threads if the user leaves a main server #### 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 #### reactOnSeen **Default:** `off` If enabled, the bot will react to messages sent to it with the emoji defined in `reactOnSeenEmoji` #### reactOnSeenEmoji **Default:** `📨` The emoji that the bot will react with when it sees a message. Requires `reactOnSeen` to be enabled. Must be pasted in the config file as the Emoji representation and not as a unicode codepoint. #### 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 #### serverGreetings **Default:** *None* When running the bot on multiple main servers, this allows you to set different greetings for each server. Example: ```ini serverGreetings.94882524378968064.message = Welcome to server ID 94882524378968064! serverGreetings.94882524378968064.attachment = greeting.png serverGreetings.541484311354933258.message[] = Welcome to server ID 541484311354933258! serverGreetings.541484311354933258.message[] = Second line of the greeting. ``` #### 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. #### createThreadOnMention **Default:** `off` If enabled, the bot will automatically create a new thread for a user who pings it. #### 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 #### updateNotificationsForBetaVersions **Default:** `off` If enabled, update notifications will also be given for new beta versions #### 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 ## Advanced options #### extraIntents **Default:** *None* If you're using or developing a plugin that requires extra [Gateway Intents](https://discord.com/developers/docs/topics/gateway#gateway-intents), you can specify them here. Example: ```ini extraIntents[] = guildPresences extraIntents[] = guildMembers ``` #### dbType **Default:** `sqlite` Specifies the type of database to use. Valid options: * `sqlite` (see also [sqliteOptions](#sqliteOptions) below) * `mysql` (see also [mysqlOptions](#mysqlOptions) below) Other databases are *not* currently supported. #### sqliteOptions Object with SQLite-specific options ##### sqliteOptions.filename **Default:** `db/data.sqlite` Can be used to specify the path to the database file #### mysqlOptions Object with MySQL-specific options ##### mysqlOptions.host **Default:** `localhost` ##### mysqlOptions.port **Default:** `3306` ##### mysqlOptions.user **Default:** *None* Required if using `mysql` for `dbType`. MySQL user to connect with. ##### mysqlOptions.password **Default:** *None* Required if using `mysql` for `dbType`. Password for the MySQL user specified above. ##### mysqlOptions.database **Default:** *None* Required if using `mysql` for `dbType`. Name of the MySQL database to use. ## 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. `"mainServerId": "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: * `mainServerId` -> `MM_MAIN_SERVER_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.