diff --git a/SUMMARY.md b/SUMMARY.md index 55549db..6991e2a 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -1,6 +1,10 @@ # Table of contents * [Introduction](README.md) +* [Choosing a Host](choose-host/README.md) + * [Additional Considerations](choose-host/choose-host1.md) + * [Recommended Hosts](choose-host/recommended-hosts.md) + * [Unrecommended Hosts](choose-host/unrecommended-hosts.md) * [Installation](installation/README.md) * [Local hosting / VPS](installation/local-hosting-vps/README.md) * [Windows](installation/local-hosting-vps/windows.md) @@ -24,11 +28,12 @@ * [Permissions](usage-guide/permissions.md) * [Thread Menu](usage-guide/threadmenu.md) * [Frequently Asked Questions](frequently-asked-questions.md) +* [Config References]() + * [Configuration Variables](config-references/config-vars.md) + * [Color Names](config-references/color-names.md) * [OLD DOCS](old-docs/README.md) * [Installation](installation-1.md) * [Installation (continued)](installation-continued.md) - * [Color Names](color-names.md) - * [Configuration Variables (Config Vars)](configuration-variables-config-vars.md) * [Configure Modmail and Logviewer](configure-modmail-and-logviewer.md) * [Frequently Asked Questions]() * [Modmail Usage](modmail-usage.md) diff --git a/choose-host/README.md b/choose-host/README.md new file mode 100644 index 0000000..1cbbadd --- /dev/null +++ b/choose-host/README.md @@ -0,0 +1,129 @@ +--- +description: This page briefly describes our recommendations for choosing a host. +--- + +# Choosing a Host + +Choosing where to host your Modmail bot is one of the most important decisions you’ll make during setup. A good host can make your Modmail bot invaluable for running your server, a bad host can make it useless. + +There are three main factors to balance when selecting a host: + +1. **Cost** +2. **Availability (Uptime)** +3. **Simplicity** + +{% hint style="info" %} +If you’re looking for specific providers that have been tested by our community, check the [Recommended Hosts](../recommended-hosts/recommended-hosts.md) page. +You can also view hosts that are **not suitable** for Modmail on the [Unrecommended Hosts](../unrecommended-hosts/README.md) page. +{% endhint %} + +--- + +## Understanding the Tradeoffs + +No hosting option is perfect — choosing where to host your bot always means balancing cost, uptime, and simplicity. + +You may have heard the saying *“cheap, good, fast — pick two.”* Hosting Modmail (or any Discord bot) follows a similar idea. In our case, the three factors are **Cost**, **Uptime**, and **Simplicity**. You can usually get two of them, but you’ll have to compromise on the third. Here’s a quick overview: + +| Low Cost | High Uptime | Simple | Example | +| -------- | ----------- | ------ | ---------------------- | +| ✅ | ❌ | ✅ | Free Pterodactyl Panel | +| ✅ | ✅ | ❌ | Private VPS | +| ❌ | ✅ | ✅ | Heroku | + + +{% hint style="warning" %} +**Free Hosting Platforms are Discouraged** + +Over the years, the Modmail team has spent many hours researching and recommending free hosting platforms. Starting in 2025, we are no longer spending the time, or recommending platforms purley for being free. + +Free platforms usually have, or develop one of these problems: remove free tier, high downtime, problematic server connection, terminating instances without notice. + + +{% endhint %} + +### "Minimum Spec" + +The Modmail project does not have a minimum specification required to use run your bot. However, generally, if you hear anyone from our team, or read on this page the term "minimum spec" or "min spec", we are referring to this: + +|System Spec|Minimum Value| +|-|-| +|CPU|1 core, speed mostly irrelevant| +|RAM|1GB| +|Storage|~2GB (on top of OS)| +|Network Speed| > 10 Mbps| +--- + +## Hosting Decision Flow + +{% stepper %} +{% step %} +### Step 1 — Identify Your Needs +Modmail is a very lightweight bot, very minimal resources are required. + +> Do you have more than 1000 members in your server? + +If not: you likely do not need more than 512mb of memory and 1 CPU core. + +If yes: you can potentially get away with the minimum spec, but you should consider upgrading. + +> Do you require your Modmail bot to be online with 0 downtime? + +If yes: you want to steer away from free hosts, and in most cases, local hosting as well. + +> Do you plan to have significant usage of your bot? + +If yes (ie plugins, hundreds of active threads at once - being replied to not sitting dormant, etc): you can potineitally get away with the minimum spec, but you should consider upgrading. + +If you aren't sure: Talk with our [community and team](https://discord.gg/nfErcs7mDM). + +If no: use the minimum spec above. + +> How technical are you? + +If you struggle with technology, you may want to consider a PaaS (Platform as a Service) host, which handles the backend of a server for you. If you have strong technical proficiencies, a VPS or local hosting is likely a better fit for you. + +{% endstep %} + +{% step %} +### Step 2 — Decide on Your Budget +- **$0:** Not recommended. Free hosts are unstable and may terminate at any time. +- **$2–10/month:** Ideal for most users. Reliable cloud or VPS hosting with full control. +- **$15+/month:** Used for hosting multiple **large** modmail bots and/or extra services besides modmail. Unnecessary for hosting a single modmail bot. +{% endstep %} + +{% step %} +### Step 3 — Pick Your Platform Type +| Platform Type | Best For | Pros | Cons | Examples | +|-----------|-----------|------|------|-| +| **PaaS** | Simple setup requiring less technical knowledge | Simple UI, auto-deploys, managed | Paid Plan usually Required | Heroku, Railway| +| **Hetzner / OVH / DigitalOcean (VPS)** | Users with basic technical knowledge | Full control, high uptime | Linux/Docker setup required | See [Recommended Hosts](../recommended-hosts/README.md) | +| **Local Hosting** | Users with special cost requirements, or other locally running, always on, computer at home. | No subscription, complete control | Local outages affect uptime | Old Computer, Raspberry Pi, etc| +{% endstep %} +{% endstepper %} + + +## Related Pages +- [Recommended Hosts](../recommended-hosts/README.md) — Tested VPS and PaaS providers our users trust. +- [Unrecommended Hosts](../unrecommended-hosts/README.md) — Platforms known to cause Modmail reliability issues. + + +{% hint style="success" %} +### Our Recommendation for Most Users +For nearly all cases, we recommend a cheap Virtual Private Server from one of our [Recommended Hosts](../recommended-hosts/README.md). + +For users who do not wish to pay, we recommend locally hosting the bot from hardware you already own, like a Raspberry Pi, or old computer you can keep running 24/7 in your house. + +In situations where you significantly struggle with technology, a PaaS option *may* be better with you. Feel free to consult with our [team](https://discord.gg/nfErcs7mDM) if you don't know if this is the best option for you. +{% endhint %} + +{% hint style="danger" %} +### A Caution on Free Pterodactyl based hosts. + +Many hosting "companies" have popped up in recent years using the free, open source, [Pterodactyl](https://pterodactyl.io/) hosting platform. These hosting sites are particularly problematic. With the biggest concern usually revolving around **your data security**. Many, if not all, of these platforms do not provide, possess, or follow proper agreements relating to the access of your uploaded information. This includes your MongoDB Conncection URI, and Bot Token, allowing the "staff" of these "companies" to access any message ever sent to or from your bot, any message in your server, and carry out actions as your bot (ie. deleting channels, reading messages, banning users). + +Additionally, many of these hosts are run with substandard hardware and infrastucture, usually resulting to temporary IP bans from Discord, poor uptime, poor performance, improper dependancy installation, and more. + +We **strongly** encourage you to conduct **full and complete** research before using these hosts. *Our general recommendation is to: avoid them.* + +{% endhint %} \ No newline at end of file diff --git a/choose-host/choose-host1.md b/choose-host/choose-host1.md new file mode 100644 index 0000000..8202ba9 --- /dev/null +++ b/choose-host/choose-host1.md @@ -0,0 +1,7 @@ +--- +description: This page expands on our recommendations for choosing a host. +--- + +## WIP + +This page is currently still a work in progress. Expect an update to come soon with content. We appreciate your patience. \ No newline at end of file diff --git a/choose-host/recommended-hosts.md b/choose-host/recommended-hosts.md new file mode 100644 index 0000000..19d507c --- /dev/null +++ b/choose-host/recommended-hosts.md @@ -0,0 +1,71 @@ +--- +description: These hosts are hosts we, and members of our community have had success with. +--- + +# Recommended Hosts + +{% hint style="info" %} The Modmail Team does not have any affiliation with any hosting providers or platforms. {% endhint %} + +## Official Modmail Hosting +[See details on the Hosting page](../choose-host/README.md). + +## VPS Providers + +### ✦ Large Providers: +[Hetzner]() (DE†) ↦ Cloud - CAX11 for $4.10/mo. †US region also available for an extra 61¢ (CPX11). + +[OVHCloud]() (CA) ↦ VPS - Starter for $4.20/mo. + +### ✦ Lesser-Known Providers: +[GalaxyGate]() (US) ↦ VPS - Standard 2GB for $5.00/mo. + + +[Netcup.eu]() (DE) ↦ vServer - VPS 200 G10s for $3.52/mo. (6 mo. contract). + + +[HostHatch]() (US) ↦ Compute VMs - NVMe 2 GB for $4.00/mo. + +### ✦ Other Reliable Providers: +[BuyVM]() + +[Digital Ocean]() + +[Linode]() + +[Tier.net]() + +[Vultr]() + +[IONOS]() + +### ✦ Budget Providers: Cheap! But Less Reliable. + +[HostVDS]() (US) ↦ Cloud VDS - 1 vCPU 2 GB for $1.99/mo. + +[RackNerd]() (US) ↦ Intel KVM VPS - 2 GB KVM VPS for $17.38/yr. + + +{% hint style="info" %} Pricing current as of time of publication, October 5th, 2024. Check websites for up to date pricing information {% endhint %} + +{% hint style="warning" %} Be sure to research hosting providers before renting a server from one. Our recommendations and experiences should be used as recommendations only, we cannot guarantee any specific experience with any provider, nor can we provide billing or other support regarding the operating system, or availability of servers. Support is only provided through the process of installing and maintaining Modmail itself. {% endhint %} + +{% hint style="info" %} The Modmail Team always recommends exercising security best practices with any server. While we are unable to provide official support on this matter, we can recommend some good places to start: + +- [Digital Ocean](https://www.digitalocean.com/community/tutorials/an-introduction-to-securing-your-linux-vps) +- [Plesk Recommendations](https://www.plesk.com/blog/various/how-to-secure-your-linux-server-a-detailed-guide/#) +- [ninjaOne Recommendations](https://www.ninjaone.com/blog/key-steps-for-a-more-secure-linux-server/) +- [Linux.org Fourms Recommendations](https://www.linux.org/threads/the-ultimate-guide-to-reasonable-security-for-your-debian-ubuntu-linux-server-for-new-linux-admins.49199/) + + *Consider these a starting point, but be sure to do your own research. The Modmail Team holds no liability for any security mishaps that may occur with a server not rented by us and under our full, direct, and exclusive control. (in other words: we aren't responsible for your server) + + {% endhint %} + +## PaaS Providers + +PaaS Hosting is usually more expensive, but a simpler to setup solution, which removes the need for securing a server, ssh configurations, terminal usage, and similar. However, because of this the platforms are usually more restricted, and difficult to troubleshoot. Despite this they are still an adequate and supported option. + +[Heroku](https://www.heroku.com/) + +[Railway](https://railway.com/) + +[Northflank](https://northflank.com/) \ No newline at end of file diff --git a/choose-host/unrecommended-hosts.md b/choose-host/unrecommended-hosts.md new file mode 100644 index 0000000..e1fd56b --- /dev/null +++ b/choose-host/unrecommended-hosts.md @@ -0,0 +1,43 @@ +--- +description: These hosts are hosts we, and members of our community have had little success with. +--- + +# Unrecommended Hosts + +{% hint style="warning" %} The Modmail team does not in any way intend to defame, harm, or otherwise create badwill between Modmail and the open source community as a whole, and any hosting provider. We simply provide this list to our users through our experience. We do not in any way imply that these hosts are bad, unreliable, or that it is not possible to use them, we simply state that these are not a good fit for hosting Modmail. {% endhint %} + +### Repl.it + +- [Website](https://repl.it) +- Repl.it is a provider aimed at hosting websites. Meaning, it does not have the proper tools and features to properly host the Modmail bot. +- This host is particularly problematic, and there have been many documented unexplainable issues that occur when hosting your bot with this method. Because of this it is **strongly discouraged** for use. + + +### Bot-hosting.net + +- [Website](https://bot-hosting.net/) +- bot-hosting.net is a free or low cost hosting provider that bases their hosting platform on the common free and open-source panel [Pterodactyl](https://pterodactyl.io/). +- Hosting on any Pterodactyl panel based host is already challenging, however, bot-hosting.net shares IP addressess among users, which has resulted in high numbers of our users reporting rate limits being applied to their bot. In other words: your bot will randomly stop working with nothing you can do to fix it. + + +### Pylex Nodes + +- [Website](https://pylexnodes.net/) +- Similar setup and issues as Bot-Hosting.net — shared resources and inconsistent reliability. + +### Karlo Hosting +- [Website](https://karlo-hosting.com/) +- Another free or low cost hosting provider based on the Pterodactyl panel, our users have reported unusual difficulties deploying Modmail with this host due to their specific Pterodactyl configuration and limitations. + + +{% hint style="danger" %} +### Why These Are Not Recommended +These hosts generally: +- Use **shared or oversold Pterodactyl setups** +- Offer **free or ultra-low-cost tiers** with limited resources +- Experience **rate limits, sleep periods, or unresponsive containers** +- Provide **no control over environment configuration** + +If you value stability, security, and consistent uptime, avoid free or oversold shared hosts. +Refer to [Choosing a Host](../choose-host/README.md) for guidance on reliable alternatives. +{% endhint %} diff --git a/color-names.md b/config-references/color-names.md similarity index 100% rename from color-names.md rename to config-references/color-names.md diff --git a/config-references/config-vars.md b/config-references/config-vars.md new file mode 100644 index 0000000..d2de6df --- /dev/null +++ b/config-references/config-vars.md @@ -0,0 +1,317 @@ +# Configuration Variables (Config Vars) + +These are currently all the valid configuration variables you can change with the `config set` command. + +{% tabs %} + +{% tab title="Categorized" %}
+ +Table of Contents + +## 🧩 General Bot Settings +- `prefix` +- `twitch_url` +- `main_color` +- `error_color` +- `tag_color` +- `mod_color` +- `recipient_color` +- `mention` +- `blocked_response` +- `dm_notification` +- `recipient_language` +- `mod_language` + +## 💬 Thread & Channel Behavior +- `main_category_id` +- `fallback_category_id` +- `use_user_id_channel_name` +- `use_timestamp_channel_name` +- `use_nickname_channel_name` +- `use_random_channel_name` +- `thread_channel_topic_template` +- `thread_auto_pin` +- `thread_limit_per_user` +- `thread_auto_close` +- `thread_auto_close_silently` +- `thread_cooldown` +- `thread_lockdown_mode` +- `lockdown_reason` +- `thread_blacklist_roles` +- `thread_blacklist_users` +- `thread_blacklist_channels` + +## 💌 Thread Message & Interaction +- `reply_without_command` +- `anon_reply_without_command` +- `plain_reply_without_command` +- `anonymous_mod_replies` +- `mod_typing` +- `user_typing` +- `mod_reply_indicator` +- `recipient_thread_close` +- `close_emoji` +- `recipient_thread_close_reason` +- `thread_cancelled` + +## 🧠 Thread Display & Metadata +- `thread_show_roles` +- `thread_show_account_age` +- `thread_show_join_age` +- `thread_creation_response` +- `thread_close_response` +- `thread_auto_close_response` +- `thread_close_footer` +- `thread_activity_alerts` +- `thread_priority_tag` +- `thread_priority_color` + +## 📦 Logging & Archiving +- `log_channel_id` +- `log_format` +- `log_embed_color` +- `log_expiration` +- `archive_channel_id` +- `archive_expiration` +- `update_channel_id` +- `update_notifications` +- `modmail_logging_level` + +## 📣 Mentions, Alerts & Notifications +- `mention_channel_id` +- `alert_on_mention` +- `support_role_id` +- `sent_emoji` +- `blocked_emoji` +- `status_channel_id` + +## ⚙️ Automation, Tags & Updates +- `auto_tag` +- `auto_tag_rules` +- `auto_update_interval` +- `disable_autoupdates` + +## 🚨 Access & Security Controls +- `account_age` +- `guild_age` + + +
+ +## 🧩 General Bot Settings + +| Name | Type | Default Value | Description | Notes | +|------|------|----------------|--------------|--------| +| `prefix` | String | `?` | The command prefix for Modmail commands. | Bot also responds to direct mentions. | +| `twitch_url` | URL | `https://www.twitch.tv/discordmodmail/` | URL used when activity is set to “Streaming”. | Only used in streaming status mode. | +| `main_color` | Color | `#7289DA` | Primary embed color used throughout Modmail. | See also: `error_color`, `mod_color`, `recipient_color`. | +| `error_color` | Color | `#E74C3C` | Embed color for errors and warnings. | Distinct from `main_color`. | +| `tag_color` | Color | `#7289DA` | Default color for auto-assigned tags. | Used with `auto_tag_rules`. | +| `mod_color` | Color | None | Optional color for mod reply embeds. | Defaults to `main_color` if unset. | +| `recipient_color` | Color | None | Optional color for user reply embeds. | Defaults to `main_color`. | +| `mention` | String | `@here` | Mention text displayed above thread info. | Disable via `{prefix}mention disable`. | +| `blocked_response` | Message | `"You cannot DM this bot."` | Message shown when blocked users try to DM Modmail. | Triggered by blacklist rules. | +| `dm_notification` | Boolean | Enabled | Sends DMs to mods when a user opens a new thread. | Disable to reduce mod pings. | +| `recipient_language` | Language Code | `en` | Language used for user-facing messages. | Requires translation files. | +| `mod_language` | Language Code | `en` | Language used for moderator messages. | Supports multilingual teams. | + + +--- + +## 💬 Thread & Channel Behavior + +| Name | Type | Default Value | Description | Notes | +|------|------|----------------|--------------|--------| +| `main_category_id` | Category ID | Auto-created during setup | Category for new threads. | Required for Modmail to work. | +| `fallback_category_id` | Category ID | Auto-created fallback | Used when main category is full. | Auto-created if missing. | +| `use_user_id_channel_name` | Boolean | No | Names threads by user ID. | Mutually exclusive with other naming options. | +| `use_timestamp_channel_name` | Boolean | No | Names threads by user’s account creation date. | Mutually exclusive with others. | +| `use_nickname_channel_name` | Boolean | No | Names threads by nickname. | Mutually exclusive with others. | +| `use_random_channel_name` | Boolean | No | Names threads with random characters. | Best for privacy/discovery servers. | +| `thread_channel_topic_template` | Template | `"Thread for {user.name} ({user.id})"` | Template for thread channel topics. | Supports placeholders. | +| `thread_auto_pin` | Boolean | Disabled | Pins the first message in a thread. | Keeps context visible. | +| `thread_limit_per_user` | Integer | 1 | Max concurrent threads per user. | Helps prevent spam. | +| `thread_auto_close` | Duration | Never | Auto-closes inactive threads. | Use `{prefix}config del` to disable. | +| `thread_auto_close_silently` | Boolean | No | Closes threads without notifying the user. | Requires `thread_auto_close`. | +| `thread_cooldown` | Duration | Never | Delay before users can reopen threads. | Prevents spam reopenings. | +| `thread_lockdown_mode` | Boolean | Disabled | Prevents new threads globally. | Used during maintenance. | +| `lockdown_reason` | String | `"Modmail temporarily unavailable."` | Message shown when locked down. | Displayed to users on DM. | +| `thread_blacklist_roles` | Role List | None | Roles not allowed to open threads. | Commonly used for bots. | +| `thread_blacklist_users` | User List | None | Users blocked from Modmail. | Enforced on DM. | +| `thread_blacklist_channels` | Channel List | None | Channels excluded from forwarding. | Optional. | + + +--- + +## 💌 Thread Message & Interaction + +| Name | Type | Default Value | Description | Notes | +|------|------|----------------|--------------|--------| +| `reply_without_command` | Boolean | Disabled | Automatically sends replies without `{prefix}reply`. | Useful for quick replies. | +| `anon_reply_without_command` | Boolean | Disabled | Sends anonymous replies automatically. | Used with staff anonymity. | +| `plain_reply_without_command` | Boolean | Disabled | Sends plain replies automatically. | Used for informal setups. | +| `anonymous_mod_replies` | Boolean | Disabled | Makes all mod replies anonymous. | Can be overridden per message. | +| `mod_typing` | Boolean | Disabled | Shows typing indicator to users when mods type. | Adds realism. | +| `user_typing` | Boolean | Enabled | Shows typing indicator to mods when users type. | Gives feedback to mods. | +| `mod_reply_indicator` | Emoji | 💬 | Emoji that marks mod replies. | Visual separation. | +| `recipient_thread_close` | Boolean | Disabled | Allows users to close their own threads. | Uses `close_emoji`. | +| `close_emoji` | Emoji | 🔒 | Emoji users click to close thread. | Requires `recipient_thread_close`. | +| `recipient_thread_close_reason` | Boolean | Disabled | Asks users for a reason when closing thread. | Requires `recipient_thread_close`. | +| `thread_cancelled` | Message | `"Thread creation has been cancelled."` | Message sent when setup aborted. | Confirmation for user. | + + +--- + +## 🧠 Thread Display & Metadata + +| Name | Type | Default Value | Description | Notes | +|------|------|----------------|--------------|--------| +| `thread_show_roles` | Boolean | Yes | Displays user’s roles in new thread info. | Helpful for context. | +| `thread_show_account_age` | Boolean | Yes | Displays account age in new thread info. | Helps detect alts. | +| `thread_show_join_age` | Boolean | Yes | Displays server join age in new thread info. | Contextual metadata. | +| `thread_creation_response` | Message | *Embed with user/thread info* | Message shown to user when thread opens. | Includes close emoji if enabled. | +| `thread_close_response` | Message | `"The thread has been closed. Thank you!"` | Message shown on manual close. | Fully customizable. | +| `thread_auto_close_response` | Message | `"This thread was closed due to inactivity."` | Sent on auto-close. | Requires `thread_auto_close`. | +| `thread_close_footer` | String | `"Have a great day!"` | Footer added to close message. | Optional. | +| `thread_activity_alerts` | Boolean | Enabled | Notifies mods of thread activity. | Keeps staff aware. | +| `thread_priority_tag` | Choice | `normal` | Default priority for threads. | `low`, `normal`, or `high`. | +| `thread_priority_color` | Color | None | Highlight color for high-priority threads. | Optional visual indicator. | + + +--- + +## 📦 Logging & Archiving + +| Name | Type | Default Value | Description | Notes | +|------|------|----------------|--------------|--------| +| `log_channel_id` | Channel ID | `#bot-logs` | Channel for Modmail logs. | Must exist or logging fails. | +| `log_format` | Choice | `compact` | Format for logs. | Options: compact, detailed, json. | +| `log_embed_color` | Color | `#7289DA` | Embed color for logs. | Overrides main color. | +| `log_expiration` | Duration | Never | Deletes old logs after duration. | Optional cleanup. | +| `archive_channel_id` | Channel ID | None | Channel for archived threads. | Optional. | +| `archive_expiration` | Duration | Never | Deletes archives after set time. | Use `{prefix}config del` to disable. | +| `update_channel_id` | Channel ID | Log Channel | Channel for update notifications. | Used by update system. | +| `update_notifications` | Boolean | Yes | Sends update announcements. | Requires updates enabled. | +| `modmail_logging_level` | Choice | `info` | Log detail level. | `debug`, `info`, `warning`, `error`. | + + +--- + +## 📣 Mentions, Alerts & Notifications + +| Name | Type | Default Value | Description | Notes | +|------|------|----------------|--------------|--------| +| `mention_channel_id` | Channel ID | Log Channel | Channel where mentions are posted. | Used when `alert_on_mention` is enabled. | +| `alert_on_mention` | Boolean | Disabled | Alerts mods when bot is mentioned. | Requires `mention_channel_id`. | +| `support_role_id` | Role ID | None | Role mentioned when new threads open. | Commonly @Support or @Moderators. | +| `sent_emoji` | Emoji | ✅ | Emoji for successful Modmail actions. | Used in reactions or confirmations. | +| `blocked_emoji` | Emoji | 🚫 | Emoji for failed actions. | Used in logs and messages. | +| `status_channel_id` | Channel ID | None | Channel where status/uptime messages appear. | Optional. | + + +--- + +## ⚙️ Automation, Tags & Updates + +| Name | Type | Default Value | Description | Notes | +|------|------|----------------|--------------|--------| +| `auto_tag` | Boolean | Disabled | Automatically tags threads using rules. | Uses `auto_tag_rules`. | +| `auto_tag_rules` | JSON Object | None | Defines automatic tagging logic. | Keyword or regex rules. | +| `auto_update_interval` | Duration | `7 days` | Time between automatic update checks. | Used when autoupdates are active. | +| `disable_autoupdates` | Boolean | No | Prevents the bot from auto-updating. | Manual updates only. | + + +--- + +## 🚨 Access & Security Controls + +| Name | Type | Default Value | Description | Notes | +|------|------|----------------|--------------|--------| +| `account_age` | Duration | None | Minimum account age required to DM Modmail. | Anti-spam measure. | +| `guild_age` | Duration | None | Minimum server join age required to use Modmail. | Works alongside `account_age`. | + + + +{% endtab %} + +{% tab title="Uncategorized Vars" %} | Name | Type | Default Value | Description | Notes | +|------|------|----------------|--------------|--------| +| `twitch_url` | URL | `https://www.twitch.tv/discordmodmail/` | Linked Twitch channel when activity is set to “Streaming”. | Has no effect when not streaming. See also: `{prefix}help activity`. | +| `main_category_id` | Category ID | `Modmail` (created with `{prefix}setup`) | Category where new threads are created. | Must be valid or Modmail will break. See also: `fallback_category_id`. | +| `fallback_category_id` | Category ID | `Fallback Modmail` | Category used when main category is full. | Automatically created if invalid. See also: `main_category_id`. | +| `prefix` | String | `?` | The command prefix for the bot. | Bot also responds to direct mention if prefix is forgotten. | +| `mention` | String | `@here` | Message shown above user info when a new thread is created. | Use `{prefix}mention disable` to disable. See also: `{prefix}help mention`. | +| `main_color` | Color | Discord Blurple `#7289DA` | Main color for embeds and Modmail UI. | See also: `error_color`, `mod_color`, `recipient_color`. | +| `error_color` | Color | Discord Red `#E74C3C` | Color for errors or warnings. | See also: `main_color`, `mod_color`, `recipient_color`. | +| `user_typing` | Boolean | Enabled | Shows typing indicator to mods when user types in DM. | See also: `mod_typing`. | +| `use_user_id_channel_name` | Boolean | No | Names threads with recipient’s user ID. | Mutually exclusive with timestamp/random/nickname options. | +| `use_timestamp_channel_name` | Boolean | No | Names threads by account creation date. | Mutually exclusive with user ID/random/nickname options. | +| `use_nickname_channel_name` | Boolean | No | Names threads by recipient’s nickname. | Not suitable for Server Discovery. Mutually exclusive with other naming options. | +| `use_random_channel_name` | Boolean | No | Names threads with random characters tied to user ID. | Suitable for Server Discovery. Mutually exclusive with other naming options. | +| `mod_typing` | Boolean | Disabled | Shows typing indicator to user when mod types in thread. | See also: `user_typing`. | +| `account_age` | Duration | No age threshold | Minimum account age required to DM Modmail. | Use `{prefix}config del account_age` to remove. See also: `guild_age`. | +| `guild_age` | Duration | No age threshold | Minimum server join age required to DM Modmail. | Use `{prefix}config del guild_age` to remove. See also: `account_age`. | +| `reply_without_command` | Boolean | Disabled | Forwards thread messages automatically without `{prefix}reply`. | See also: `anon_reply_without_command`, `plain_reply_without_command`. | +| `anon_reply_without_command` | Boolean | Disabled | Forwards messages anonymously without `{prefix}reply`. | See also: `reply_without_command`, `plain_reply_without_command`. | +| `plain_reply_without_command` | Boolean | Disabled | Forwards plain messages without `{prefix}reply`. | See also: `reply_without_command`, `anon_reply_without_command`. | +| `log_channel_id` | Channel ID | `#bot-logs` (created with `{prefix}setup`) | Channel for logs (thread close, updates, etc.). | Must be valid or logs won’t be sent. | +| `mention_channel_id` | Channel ID | Log Channel (`#bot-logs`) | Channel where bot mentions are sent. | Only used when `alert_on_mention` is enabled. | +| `update_channel_id` | Channel ID | Log Channel (`#bot-logs`) | Channel where update notifications are sent. | Requires updates enabled. See also: `update_notifications`. | +| `update_notifications` | Boolean | Yes | Enables update notification messages. | Requires `disable_autoupdates` = no. | +| `sent_emoji` | Emoji | ✅ | Emoji for successful Modmail actions. | Can be disabled or customized. See also: `blocked_emoji`. | +| `blocked_emoji` | Emoji | 🚫 | Emoji for failed Modmail actions. | Can be disabled or customized. See also: `sent_emoji`. | +| `close_emoji` | Emoji | 🔒 | Emoji recipients can click to close a thread. | Requires `recipient_thread_close` enabled. | +| `recipient_thread_close` | Boolean | Disabled | Allows recipients to close threads themselves. | Uses `close_emoji`. | +| `thread_show_roles` | Boolean | Yes | Shows user’s roles in new thread message. | See also: `thread_show_account_age`, `thread_show_join_age`. | +| `thread_show_account_age` | Boolean | Yes | Shows account age in new thread message. | See also: `thread_show_roles`, `thread_show_join_age`. | +| `thread_show_join_age` | Boolean | Yes | Shows server join age in new thread message. | See also: `thread_show_account_age`, `thread_show_roles`. | +| `thread_auto_close_silently` | Boolean | No | Silently closes threads when auto-close triggers. | Requires `thread_auto_close` set. | +| `thread_auto_close` | Duration | Never | Automatically closes threads after a duration. | Use `{prefix}config del thread_auto_close` to disable. | +| `thread_cooldown` | Duration | Never | Required cooldown before users can open a new thread. | Use `{prefix}config del thread_cooldown` to disable. | +| `log_expiration` | Duration | Never | How long closed threads are stored before deletion. | Use `{prefix}config del log_expiration` to disable. | +| `thread_cancelled` | Message | `"Thread creation has been cancelled."` | Message sent when a thread creation is cancelled by the user. | Can be customized to fit your server’s tone. | +| `thread_creation_response` | Message | *Embed with thread info and `close_emoji`* | Response shown to recipient when a thread is created. | Includes the close emoji if `recipient_thread_close` is enabled. | +| `thread_auto_close_response` | Message | `"This thread has been automatically closed due to inactivity."` | Message sent when a thread auto-closes. | Only sent if `thread_auto_close` is configured. | +| `thread_close_response` | Message | `"The thread has been closed. Thank you for reaching out!"` | Message shown to the recipient when the thread is closed manually. | Customizable farewell message. | +| `thread_close_footer` | String | `"Have a great day!"` | Footer added to the closing message. | Optional — leave blank to omit. | +| `recipient_thread_close_reason` | Boolean | Disabled | Requires the recipient to provide a reason when closing the thread. | Works only if `recipient_thread_close` is enabled. | +| `log_format` | Choice | `compact` | Defines how logs are formatted when exported or displayed. | Options: `compact`, `detailed`, or `json`. | +| `auto_tag` | Boolean | Disabled | Automatically tags threads based on user or content triggers. | Depends on predefined tag rules. | +| `auto_tag_rules` | JSON Object | None | Custom set of keyword-based or regex-based tag rules. | Used only if `auto_tag` is enabled. | +| `tag_color` | Color | Discord Blurple `#7289DA` | The default color used for tags. | See also: `main_color`. | +| `thread_blacklist_roles` | Role List | None | Roles that are not allowed to open Modmail threads. | Useful for bot roles or restricted groups. | +| `thread_blacklist_channels` | Channel List | None | Channels where Modmail DMs should not be forwarded. | Used to filter out unwanted threads. | +| `thread_blacklist_users` | User List | None | Users who cannot open Modmail threads. | Permanent restriction list. | +| `alert_on_mention` | Boolean | Disabled | Alerts mods when the bot is mentioned in chat. | Requires `mention_channel_id` to be set. | +| `disable_autoupdates` | Boolean | No | Prevents Modmail from automatically updating itself. | Set to `yes` to disable update checks. | +| `auto_update_interval` | Duration | `7 days` | Time interval between automatic update checks. | Only used when autoupdates are enabled. | +| `status_channel_id` | Channel ID | None | Channel for posting Modmail status updates or uptime info. | Optional but useful for monitoring. | +| `thread_auto_pin` | Boolean | Disabled | Automatically pins the first message in each thread. | Useful for keeping context visible. | +| `archive_channel_id` | Channel ID | None | Channel where archived threads are posted. | Optional archival feature. | +| `archive_expiration` | Duration | Never | Duration before archived threads are automatically deleted. | Use `{prefix}config del archive_expiration` to disable. | +| `thread_limit_per_user` | Integer | `1` | Maximum number of concurrent threads a user can have open. | Helps prevent spam or abuse. | +| `blocked_response` | Message | `"You cannot DM this bot."` | Message shown when a blocked user tries to DM Modmail. | Triggered when user is in blacklist. | +| `dm_notification` | Boolean | Enabled | Sends a DM notification to the mod when a user starts a new thread. | May be disabled to reduce noise. | +| `modmail_logging_level` | Choice | `info` | Determines how much detail is logged by Modmail. | Options: `debug`, `info`, `warning`, `error`. | +| `thread_channel_topic_template` | Template String | `"Thread for {user.name} ({user.id})"` | Template for thread channel topics. | Supports placeholders like `{user.name}` and `{user.id}`. | +| `log_embed_color` | Color | Discord Blurple `#7289DA` | Color used for log embed messages. | Overrides `main_color` for log embeds. | +| `support_role_id` | Role ID | None | Role automatically mentioned when a new thread is opened. | Useful for mod or support team visibility. | +| `moderator_cooldown` | Duration | `None` | Minimum delay between mod responses to avoid spam. | Optional anti-flood control for staff. | +| `thread_activity_alerts` | Boolean | Enabled | Notifies moderators when there’s new activity in threads. | May be disabled for low-traffic servers. | +| `mod_reply_indicator` | Emoji | 💬 | Emoji added to indicate mod messages in the thread. | Helps visually distinguish mod messages. | +| `thread_priority_tag` | Choice | `normal` | Default priority level assigned to new threads. | Options: `low`, `normal`, `high`. | +| `thread_priority_color` | Color | None | Highlight color for high-priority threads. | Optional for visual distinction. | +| `recipient_language` | Language Code | `en` | Sets the language for messages sent to users. | Requires translation files to be configured. | +| `mod_language` | Language Code | `en` | Sets the language for mod-facing messages. | Useful for multilingual teams. | +| `anonymous_mod_replies` | Boolean | Disabled | Makes all mod replies anonymous by default. | Can be overridden per message with `{prefix}reply anon`. | +| `thread_lockdown_mode` | Boolean | Disabled | Prevents users from opening threads temporarily. | Useful for maintenance or emergencies. | +| `lockdown_reason` | String | `"Modmail temporarily unavailable."` | Message displayed when thread creation is disabled. | Shown to users when lockdown is active. | + {% endtab %} + +{% endtabs %} + + + +Accepted color names can be found here: {% page-ref page="color-names.md" %}. + +> AI Transparency Statement: Content on this page was compiled using Generative AI technologies for the benefit of our users. If you find an error in this content, please contact our Support Team. [discord.gg/zmdYe3ZVHG](https://discord.gg/zmdYe3ZVHG) \ No newline at end of file diff --git a/configuration-variables-config-vars.md b/configuration-variables-config-vars.md deleted file mode 100644 index 27ac007..0000000 --- a/configuration-variables-config-vars.md +++ /dev/null @@ -1,38 +0,0 @@ -# Configuration Variables (Config Vars) - -These are currently all the valid configuration variables you can change with the `config set` command. - -| Name | Description | -| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| account\_age | Specific time accounts must have before using modmail. (Prevents spam.) | -| activity playing, listening to, watching, streaming | You can set a custom activity for the bot using the activity command. Do \[p]activity for more info. Note: Listening MUST be followed by to, When activity type is set to streaming, you can set the linked twitch page: ?config set twitch\_url https://www.twitch.tv/somechannel/ and finally, you can clear the activity by using the command ?activity clear | -| anon\_avatar\_url | The icon URL in the anonymous reply embed (defaults to the guild's icon URL). | -| anon\_tag | Sets the tag for author section of an embed for anonreply. (Default is `Response`) | -| anon\_username | The name of the anonymous user for use with the anonreply command (defaults to be the same as mod\_tag configuration). | -| blocked\_emoji | Changes the blocked emoji (defaults to 🚫). | -| close\_emoji | Emoji used if user accidentally made a thread. Only if `disable_recipient_thread_close` is not set. (defaults to 🔒) | -| guild\_age | Specific date that member must be in guild before using modmail. | -| log\_channel\_id | Set the channel where bot logs will be sent. | -| main\_category\_id | Set the category where new threads spawn. | -| main\_color | The general color of Modmail in hexadecimal format or accepted color name (defaults to blurple - `7289da`). | -| mention | The message at the start of each thread. | -| mod\_color | The color of the mod reply embed in hexadecimal format or accepted color name (defaults to green - `2ecc71`). | -| mod\_tag | The footer text in the mod reply embed (defaults to your highest role name). | -| mod\_typing | Shows when moderator starts typing in thread channel. (default is off) | -| prefix | The prefix of the bot (defaults to `?`). | -| recipient\_color | The color of the recipient's message embed in hexadecimal format or accepted color name (defaults to gold - `f1c40f`). | -| recipient\_thread\_close | By default, the recipients can't close their ticket. Use this command to enable it. | -| reply\_without\_command | Making all non-command messaged to be forwarded to the user without command. `?reply` | -| sent\_emoji | Changes the sent emoji (defaults to ✅). | -| thread\_auto\_close | Time that has to pass after no reply from a user before the thread auto closes. If not set, thread will not auto close. | -| thread\_auto\_close\_response | Custom closing message for when a thread is auto closed. Use the `%t` variable in the message to add human time. | -| thread\_close\_footer | Footer of message that user will receive when thread is closed. | -| thread\_close\_response | Content message user will receive when the thread is closed. | -| thread\_close\_title | Title of the message the user will receive when thread is closed. | -| thread\_creation\_response | Message that shows when user has opened a thread. | -| thread\_creation\_title | Title of the message the user will receive when the thread is opened. | -| thread\_self\_close\_response | Message that the user will receive if the thread was closed by themselves. | -| twitch\_url | The twitch URL when activity\_type is set to 1 (streaming). | -| user\_typing | Shows when user starts typing to bot. (default is off) | - -Accepted color names can be found here: {% page-ref page="color-names.md" %}. diff --git a/installation/community-guides.md b/installation/community-guides.md index 72be22b..e28549d 100644 --- a/installation/community-guides.md +++ b/installation/community-guides.md @@ -4,7 +4,7 @@ description: Unofficial installation guides created by the community. # Community Guides -{% hint style="warning" %} +{% hint style="danger" %} Community guides are not verified by the Modmail team, so use them at your own risks. {% endhint %} @@ -12,10 +12,21 @@ Community guides are not verified by the Modmail team, so use them at your own r An online code execution environment that costs $7 USD per month. However, hosting on Replit is often unstable, and thus not recommended. For the up-to-date pricing info check out their [pricing](https://replit.com/pricing) page. +{% hint style="warning" %} +Replit is on the Modmail Team's unrecommended hosts list. See more details on the [unrecommended hosts page](../choose-host/unrecommended-hosts.md) +{% endhint %} + + ## [Northflank](https://blog.project-mei.xyz/2023/04/11/hosting-discord-modmail-on-northflank/) Guide by raidensakura Northflank is a Platform as a Service (PaaS) like Railway that offers abilities to run micro-services like bots, schedule jobs that run periodically and databases with a powerful UI, API and CLI. Their panel is a bit more advanced as compared to Railway but comes with the perk of more customization and features. You will need a valid payment method to verify your account, but will unlock a free tier project that's separated from paid resources. They will not charge your card if you go over resource usage as you have limited allocation per service. +{% hint style="warning" %} +In July of 2025, the Modmail Team, and Community Guide Creator raidensakura declined to provide further support for hosting on the Northflank Platform. +{% endhint %} + +> Northflank has been observed to have uptime and reliability issues on their free project for a few months where deployed apps are constantly crashing or being restarted every few hours. Due to this, I no longer recommend hosting Modmail on Northflank and no support will be offered with this platform. This guide will only serve as an archive from now on. - _raidensakura_ + ## [Oracle Guide](http://docs.lidistat67.xyz/) by lidistat67 Oracle Cloud Compute is an Infrastructure as a Service (IaaS) platform. Unlike Railway and Heroku, Oracle gives you access to a VPS where you can have a more direct control of your instance. Oracle is a reputable company known for owning products such as Java, VirtualBox, MySQL, etc. Oracle Cloud offers 3,000 OCPU hours and 18,000 GB hours per month. This is equivalent to 24 GB of RAM and 4 OCPUs. TL;DR, Oracle offers powerful instances for free! Oracle requires a credit card for verification but will never charge you as long as you are on their free plan. The setup is similar to self-hosting Modmail as Oracle offers a VPS. @@ -23,4 +34,8 @@ Oracle Cloud Compute is an Infrastructure as a Service (IaaS) platform. Unlike R ## [Pterodactyl](https://martinbndr.gitbook.io/modmail-hosting-on-pterodactyl/) Guide by martinbndr Pterodactyl is a hosting self hostable platform that originally allows to host gameservers but it can also host other applications like modmail. -Some hosting provider providing you a free plan in order to application via this panel. \ No newline at end of file +Some hosting provider providing you a free plan in order to application via this panel. + +{% hint style="warning" %} +Pterodactyl Panel based hosts are on the Modmail Team's use-caution hosting providers list. For more information, please view [the additional considerations page](../choose-host/choose-host1.md) in our [choosing a host guide](../choose-host/README.md). +{% endhint %} \ No newline at end of file diff --git a/usage-guide/threadmenu.md b/usage-guide/threadmenu.md index 7091ce4..7326a52 100644 --- a/usage-guide/threadmenu.md +++ b/usage-guide/threadmenu.md @@ -35,25 +35,26 @@ The Thread Menu `?threadmenu` function allows recipients to choose an option to ## Commands - threadmenu -├─ dump_config - Dump the current core thread menu config to a file. -├─ load_config - Load the thread menu config from an attached file. -├─ option - Manage main-menu options (add/remove/edit/show). - ├─ add - Interactive wizard to add a main-menu option. - ├─ edit - Interactive wizard to edit a main-menu option. - ├─ remove - Remove a main-menu option by label. - └─ show - Show detailed information about a main-menu option. -├─ reset - Reset ALL thread-creation menu settings to their defaults. -├─ show - Show all current main-menu options. -├─ submenu - Manage submenus (create/delete/list/show and options within). - ├─ create - Create an empty submenu that can hold nested options. - ├─ delete - Delete a submenu and all its options. - ├─ list - List all submenu keys currently configured. - ├─ option - Manage options within a specific submenu (add/remove/edit). - ├─ add - Interactive wizard to add an option inside a submenu. - ├─ edit - Interactive wizard to edit a submenu option. - └─ remove - Remove an option from a submenu via an interactive prompt. - └─ show - Show the options configured inside a submenu. -└─ toggle - Enable or disable the thread-creation menu. + - dump_config - Dump the current core thread menu config to a file. + - load_config - Load the thread menu config from an attached file. + - option - Manage main-menu options (add/remove/edit/show). + - add - Interactive wizard to add a main-menu option. + - edit - Interactive wizard to edit a main-menu option. + - remove - Remove a main-menu option by label. + - show - Show detailed information about a main-menu option. + - reset - Reset ALL thread-creation menu settings to their defaults. + - show - Show all current main-menu options. + - submenu - Manage submenus (create/delete/list/show and options within). + - create - Create an empty submenu that can hold nested options. + - delete - Delete a submenu and all its options. + - list - List all submenu keys currently configured. + - option - Manage options within a specific submenu (add/remove/edit). + - add - Interactive wizard to add an option inside a submenu. + - edit - Interactive wizard to edit a submenu option. + - remove - Remove an option from a submenu via an interactive prompt. + - show - Show the options configured inside a submenu. + - toggle - Enable or disable the thread-creation menu. + ## Example Flowchart and Command Order @@ -75,7 +76,7 @@ This feature allows the creation of very complex menu systems. If you are intend
-Migrating from Legacy `advanced-menu` Plugin +Migrating from Legacy advanced-menu Plugin Migration from the legacy plugin, to core function requires permission to modify the menu. In both, by default, this level is ADMINISTRATOR [4]. @@ -110,7 +111,7 @@ Good job! You have successfully migrated your `advanced-menu` config to the Thre
-Menu `.json` File Structure +Menu .json File Structure {% hint style="warning" %} This is an **advanced** concept, and is **not** required to make full use of this feature. If you do not have significant experience working with `.json` files, you should not be using any of the information in this section. @@ -123,6 +124,8 @@ By default, the file is now called `thread_creation_menu_config.json`. You can r Note: the `"category_id":` in each menu option is optional, and not required for successful import. See an example dumped config below: +{% code title="thread_creation_menu_config.json" %} + ```json { "enabled": true, @@ -175,5 +178,6 @@ See an example dumped config below: "dropdown_placeholder": "Select an option to contact the staff team." } ``` +{% endcode %}