diff --git a/.gitbook/assets/Intents-Review-1.png b/.gitbook/assets/Intents-Review-1.png new file mode 100644 index 0000000..984c57e Binary files /dev/null and b/.gitbook/assets/Intents-Review-1.png differ diff --git a/.gitbook/assets/Intents-Review-2.png b/.gitbook/assets/Intents-Review-2.png new file mode 100644 index 0000000..dcf56da Binary files /dev/null and b/.gitbook/assets/Intents-Review-2.png differ diff --git a/.gitbook/assets/Intents-Review-3.png b/.gitbook/assets/Intents-Review-3.png new file mode 100644 index 0000000..2fc2466 Binary files /dev/null and b/.gitbook/assets/Intents-Review-3.png differ diff --git a/SUMMARY.md b/SUMMARY.md index e2ebf5d..6cbe2d5 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -27,9 +27,11 @@ * [Permissions](usage-guide/permissions.md) * [Thread Menu](usage-guide/threadmenu.md) * [Frequently Asked Questions](frequently-asked-questions.md) + * [Intents Review Process](faq/intents-review.md) + * [Instance Privacy Policy](faq/) * [Config References]() * [Configuration Variables](config-references/config-vars.md) * [Color Names](config-references/color-names.md) * [Archived Documentation](old-docs/README.md) * [Configure Modmail and Logviewer](old-docs/configure-modmail-and-logviewer.md) - * [Frequently Asked Questions](old-docs/frequently-asked-questions-old.md) + * [Frequently Asked Questions](old-docs/frequently-asked-questions-old.md) \ No newline at end of file diff --git a/faq/intents-review.md b/faq/intents-review.md new file mode 100644 index 0000000..56da8c3 --- /dev/null +++ b/faq/intents-review.md @@ -0,0 +1,207 @@ +--- +description: Assistance from the Modmail Team on the intents review process. +--- + +# Discord Intents Review Process + +{% hint style="info" %} +This process does not apply to a majority of Modmail user's. The only time a Modmail bot will need to go through Discord's Intent Review Process is in one of the following two cases: +1. *(for bots in only one server):* If the server your bot is in is close to, or above 10,000 members. +2. *(for bots in multiple servers):* If the combined member count of all the servers your bot is in is close to, or over 10,000 members. +{% endhint %} + +## Background + +Discord uses Gateway Intents to control what information is sent to your bot. Some intents, including **Message Content**, **Server Members**, and **Presence**, are considered **Privileged Intents** because they provide access to data that Discord considers more sensitive from a privacy and security perspective. Discord limits access to these intents to ensure developers only collect the information necessary for their bot's functionality. + +Modmail requires the **Message Content Intent** to read user messages and create tickets, and the **Server Members Intent** for user information features. Discord now determines privileged intent review eligibility based on the **total number of users your bot can access**, rather than the number of servers your bot is in. Applications with access to 10,000 or more users must complete Discord's intent review process before using privileged intents. During review, Discord will ask why your bot needs the requested intents and how the data is used. For Modmail, clearly explain that message content is required to receive, relay, and manage support tickets, and provide screenshots or videos demonstrating these features if requested. + + +## Intents Request Form + +

Intents Application Form for Application Details and Server (Guild) Members Intent

+

Questions for Prescence Intent Not Required for Modmail.

+

Message Content Intent Questions and Certification of Answers

+ +## Suggested Responses + +
+ +Application Details + +{% code title="Application Description" lineNumbers="false" %} + +``` +What does your application do? Please be as detailed as possible... +------------------------------------------------------------------- +Modmail is a shared inbox bot for server moderation. When a user sends a Direct Message to the bot, it automatically creates a dedicated text channel (a "thread") within a designated staff category in our Discord server. Server staff can read the user's messages in this channel and reply using bot commands. The bot then relays these staff replies back to the user via Direct Message. This allows for organized, private, and collaborative support between users and the moderation team. + +``` + +{% endcode %} + +{% code title="Application Description" lineNumbers="false" %} + +``` +Do you have a public Privacy Policy telling your users about their data usage? +------------------------------------------------------------------- +Select: Yes(required if for any applicayion using the intents or with more then 100 servers.) or No. +``` + +{% endcode %} + +{% hint style="info" %} +You will need to adopt a privacy policy for your bot. We have a version you can opt to use [here](privacy-policy.md). +{% endhint %} + +
+
+ +Server Members Intent + +{% code title="Question 1" lineNumbers="false" %} + +``` +Why do you need the Server Members intent? +------------------------------------------------------------------- +Modmail requires the Server Members Intent to accurately check a user's membership status. + +When a user initiates a Direct Message with the bot, the bot must scan the user's shared servers to route the message to the correct server's staff team. Additionally, the bot uses member data to verify staff permissions, ensuring that only authorized moderators can view the modmail threads, use staff commands, and reply to users. + +Finally, tracking member leave events is necessary to immediately detect if a user has left the server, informing the moderation team whether replying to the individual is still possible. + +``` + +{% endcode %} + +{% code title="Question 2" lineNumbers="false" %} + +``` +Please provide links to screenshots and/or videos that demonstrate your use case +------------------------------------------------------------------- +link + +``` + +{% endcode %} + +{% code title="Question 3" lineNumbers="false" %} + +``` +Are you storing any API Data off-platform (outside of Discord)? +------------------------------------------------------------------- +Select: Yes + +``` + +{% endcode %} + + +{% code title="Question 4" lineNumbers="false" %} +``` +Are you storing API Data for 30 days or less? +------------------------------------------------------------------- +Select: No + +``` +{% endcode %} + +{% code title="Question 5" lineNumbers="false" %} +``` +How do users contact you to request deletion of their activity data? +------------------------------------------------------------------- +Users can request the deletion of their data by sending a Direct Message to the bot itself to contact the server staff, or by directly messaging one of the server administrators. + +``` +{% endcode %} + +{% code title="Question 6" lineNumbers="false" %} +``` +Are you encrypting the data that you store at rest, as is required by our developer policy? +------------------------------------------------------------------- +Select: Yes + +``` +{% endcode %} +
+ +
+ +Message Content Intent +{% code title="Question 1" lineNumbers="false" %} +``` +Can users opt-out of having their message content data tracked? +------------------------------------------------------------------- +Select: Yes +``` +{% endcode %} + +{% code title="Question 2" lineNumbers="false" %} +``` +Are you storing message content data off-platform (outside of Discord)? +------------------------------------------------------------------- +Select: Yes +``` +{% endcode %} + +{% code title="Question 3" lineNumbers="false" %} +``` +Are you storing user message content data for 30 days or less? +------------------------------------------------------------------- +Select: No +``` +{% endcode %} + + +{% code title="Question 4" lineNumbers="false" %} +``` +How do users contact you to request deletion of their activity data? +------------------------------------------------------------------- +Users can request the deletion of their data by sending a Direct Message to the bot itself to contact the server staff, or by directly messaging one of the server administrators. +``` +{% endcode %} + +{% code title="Question 5" lineNumbers="false" %} +``` +Are you encrypting the data that you store at rest, as is required by our developer policy? +------------------------------------------------------------------- +Select: Yes +``` +{% endcode %} + +{% code title="Question 6" lineNumbers="false" %} +``` +Will the message content data be used to train machine learning or AI Models? +------------------------------------------------------------------- +Select: No +``` +{% endcode %} + +{% code title="Question 6" lineNumbers="false" %} +``` +Why do you need the Message Content intent? +------------------------------------------------------------------- +The core functionality of Modmail relies on processing, relaying, and logging message content sent within the server's moderation channels. The bot requires the Message Content intent to read the messages sent by staff members inside the server's modmail threads, allowing the bot to forward those replies back to the user. Additionally, the intent is necessary to monitor and log internal staff-only discussions within these server channels to preserve a complete and accurate moderation history for future reference. Without the Message Content intent, the bot cannot detect staff replies or archive internal server logs, rendering the moderation workflow non-functional. + +``` +{% endcode %} + +{% code title="Question 7" lineNumbers="false" %} +``` +Please provide links to screenshots and/or videos that demonstrate your use case +------------------------------------------------------------------- +[link] +``` +{% endcode %} +
+
+ +Presence Intent + +While we often recommend the Presence intent to allow for compatibility with a number of third party plugins, it is not a requirement for the core bot. + +Our current stance as a team is that if a plugin requires the presence intent, then the plugin developer is responsible for providing an articulatable reason to users to use during the intents review process. + +If they require assistance with this, they can contact the Modmail bot in our official [support server](https://discord.gg/cnUpwrnpYb). + +
\ No newline at end of file diff --git a/faq/privacy-policy.md b/faq/privacy-policy.md new file mode 100644 index 0000000..6ae053f --- /dev/null +++ b/faq/privacy-policy.md @@ -0,0 +1,163 @@ +--- +description: Sample Bot Privacy Policy that can be used by instances at their discretion +--- + +# Privacy Policy + +{% hint style="info" %} +This Privacy Policy only applies to Modmail Instances hosted by administrators who choose to use it. If a bot administrator has provided you this privacy policy, they have agreed to use it for their specific instance. If you have any questions regarding the validity of this privacy policy for any specific Modmail instance, please contact the relevant staff team. +{% endhint %} + +Last Updated: June 17th, 2026 + +This Privacy Policy explains how Modmail (referred to as "the Bot", "we", or "us") collects, uses, stores, and protects your data. The Bot is an instance of the open-source [modmail-dev/modmail](https://github.com/modmail-dev/modmail) project and is hosted independently by the administrators of the Discord server. + +By interacting with the Bot, you consent to the data practices described in this policy. This policy is designed to comply with the [Discord Developer Terms of Service](https://support-dev.discord.com/hc/en-us/articles/8562894815383-Discord-Developer-Terms-of-Service) and [Developer Policy](https://support-dev.discord.com/hc/en-us/articles/8563934450327-Discord-Developer-Policy). + +## 1. Data We Collect + +When you send a direct message to the Bot to initiate a support thread or interact with an active thread, we collect and store the following information: + +1. **User Data:** Your Discord User ID, username, and avatar. +2. **Message Content:** The text content, attachments, and timestamps of any messages sent to the Bot. +3. **Server Data:** Relevant Guild (Server) IDs and Channel IDs required to route your messages to the correct moderation team. +4. **Action Logs:** Metadata related to the thread, such as when it was opened, closed, or transferred by moderators. + + +## 2. How We Store Your Data + +The [modmail-dev/modmail](https://github.com/modmail-dev/modmail) application does not store data on Discord's infrastructure once a thread is archived ("closed"). Instead, all collected data (including message logs and user identifiers) is exported and stored off-platform in a MongoDB database. + +This database is managed independently by the individual or team hosting the Bot instance. We implement reasonable security measures to protect your data from unauthorized access. + + +## 3. How We Use Your Data + +The data we collect is strictly used to provide and maintain the functionality of the Bot. Specifically, we use it for: + +1. **Facilitating Communication:** Relaying messages between you and the server's moderation or support staff. +2. **Record Keeping:** Maintaining an accurate history of support requests, appeals, or reports for server staff to reference. +3. **Service Improvement:** Allowing server administrators to review past interactions to improve community guidelines and support responses. + +## 4. Data Sharing and Disclosure + +Your data is highly restricted. We do not sell, monetize, or trade your personal information. Your data is only accessible to: + +1. **Authorized Server Staff:** Moderators and administrators of the Discord server who have the necessary permissions to view Modmail threads and logs. +2. **The Database Administrator:** The technical individual responsible for hosting the MongoDB instance and keeping the Bot online.[^1] +3. **MongoDB Atlas Employees:** Select employees of the MongoDB Atlas team may have the ability to access the data. Their usage is restricted and governed by their [privacy policy](https://www.mongodb.com/legal/privacy/privacy-policy). + +We will not share your data with any third parties unless explicitly required to do so by law or to comply with Discord's Trust and Safety requests. + +## 5. Data Retention + +Chat logs and associated user identifiers are retained indefinitely within our MongoDB database to ensure server staff have a consistent historical record of all moderation and support interactions. + +## 6. Your Rights and Data Deletion + +Under the Discord Developer Policies, you have the right to request the deletion of your personal data. If you wish to have your Modmail logs and associated identifying information permanently removed from our off-platform MongoDB database, you may exercise this right by: + +1. Sending a message directly to the Bot requesting data deletion. +2. Contacting the server administrators or the contact person listed below. + +Upon receiving a valid request, we will purge your identifying information and message content from our database within 14 days. + +## 7. Contact Information + +If you have any questions, concerns, or data deletion requests regarding this Privacy Policy or the Bot's operation, please contact: + +1. The Bot directly; or +2. Any member of the server's staff team; or +3. The owner of the Discord server. + +[^1]: In almost all cases, this is a member of the authorized server staff. + +{% hint style="info" %} +**Server Owners** + +If you do not want this one size fits all option, you can use the template below as a starting point. +
+ +Basic Template + +This Privacy Policy explains how `[Insert Bot Name]` (referred to as "the Bot", "we", or "us") collects, uses, stores, and protects your data. This Bot is an instance of the open-source [modmail-dev/modmail](https://github.com/modmail-dev/modmail) project and is hosted independently by the administrators of `[Insert Discord Server Name]`. + +By interacting with the Bot, you consent to the data practices described in this policy. This policy is designed to comply with the [Discord Developer Terms of Service](https://support-dev.discord.com/hc/en-us/articles/8562894815383-Discord-Developer-Terms-of-Service) and [Developer Policy](https://support-dev.discord.com/hc/en-us/articles/8563934450327-Discord-Developer-Policy). +1. Data We Collect + +When you send a direct message to the Bot to initiate a support thread or interact with an active thread, we collect and store the following information: + +1. User Data: Your Discord User ID, username, and avatar. +2. Message Content: The text content, attachments, and timestamps of any messages sent to the Bot. +3. Server Data: Relevant Guild (Server) IDs and Channel IDs required to route your messages to the correct moderation team. +4. Action Logs: Metadata related to the thread, such as when it was opened, closed, or transferred by moderators. + +2. How We Store Your Data + +The [modmail-dev/modmail](https://github.com/modmail-dev/modmail) application does not store data on Discord's infrastructure once a thread is archived. Instead, all collected data (including message logs and user identifiers) is exported and stored off-platform in a MongoDB database. + +This database is managed independently by the individual or team hosting this Bot instance. We implement reasonable security measures within the database environment to protect your logs from unauthorized access. +3. How We Use Your Data + +The data we collect is strictly used to provide and maintain the functionality of the Bot. Specifically, we use it for: +1. Facilitating Communication: Relaying messages between you and the server's moderation or support staff. +2. Record Keeping: Maintaining an accurate history of support requests, appeals, or reports for the server staff to reference in the future. +3. Service Improvement: Allowing server administrators to review past interactions to improve community guidelines and support responses. + +4. Data Sharing and Disclosure + +Your data is highly restricted. We do not sell, monetize, or trade your personal information. Your data is only accessible to: + +1. Authorized Server Staff: Moderators and administrators of `[Insert Discord Server Name]` who have the necessary permissions to view Modmail threads and logs. +2. The Database Administrator: The technical individual(s) responsible for hosting the MongoDB instance and keeping the Bot online. + a. Database Administrator(s): `[Insert Names of Database Administrators Here]` +3. MongoDB Atlas Employees: Select employees of the MongoDB Atlas team may have the ability to access the data. Their usage is restricted and governed by their [privacy policy](https://www.mongodb.com/legal/privacy/privacy-policy). +4. `[Insert Name of Hosting Company]` Employees: Select employees of `[Insert Name of Hosting Company]` are able to access the data due to their ability to access the MongoDB connection information. Their privacy policy is defined [here](`[Insert URL to Hosting Company Privacy Policy Here]`). + +We will not share your data with any third parties unless explicitly required to do so by law or to comply with Discord's Trust and Safety requests. + +5. Data Retention + +Chat logs and associated user identifiers are retained `indefinitely/(OR)[Insert Log Retention Time Here]` within our MongoDB database to ensure server staff have a consistent historical record of all moderation and support interactions. + +6. Your Rights and Data Deletion + +Under the Discord Developer Policies, you have the right to request the deletion of your personal data. If you wish to have your Modmail logs and associated identifying information permanently removed from our off-platform MongoDB database, you may exercise this right by: +1. Sending a message directly to the Bot requesting data deletion. +2. Contacting the server administrators or the contact person(s) listed below. + +Upon receiving a verifiable request, we will manually purge your identifying information and message content from our database within [Insert Number, e.g., 30] days. +7. Contact Information + +If you have any questions, concerns, or data deletion requests regarding this Privacy Policy or the Bot's operation, please contact us at: + +1. Discord User(s): `[Insert Discord Username(s) of the Bot Owner/Administrator(s)]` +2. Email: `[Insert Contact Email, if applicable]` +3. Server: `[Insert Invite Link or instructions on how to reach staff]` +
+{% endhint %} + +{% hint style="info" %} +**Server Owners** + +Please note that by using the Privacy Policy on our Docs site without modification, you are making legally binding promises to your users and to Discord. These promises include, but are not limited to: +1. Strict Data Sharing Limitations + +> You are agreeing that you will not share user data with any third parties unless required by law. This means you cannot share Modmail logs with other Discord servers, community ban lists, global moderation databases, or any external entities. If you do so: you are violating this privacy policy, which could carry civil penalties in some jurisdictions. +2. Infrastructure and Hosting Trust + +> The policy states that only server staff and the database administrator have access to the logs. You must ensure that your hosting provider and your database host are secure and trustworthy. If your hosting provider has weak security and your database leaks, the responsibility falls entirely on you. +(This is primarily a concern for individuals using hosting providers that are not established, see our comments on [unrecommended hosts](../choose-host/unrecommended-hosts.md).) + +3. Binding Deletion Timelines + +> If you state that you will delete data upon request within 14 days, you must have a reliable, manual process to find and purge a user's data from your MongoDB cluster within that exact timeframe. Failure to honor data deletion requests is a direct violation of the Discord Developer Terms of Service and can result in action taken against your account. If you fail to honor this you also: are violating this privacy policy, which could carry civil penalties in some jurisdictions. + +4. Managing Staff Access + +> Because your policy guarantees that only authorized staff have access to user data, you must rigorously manage permissions. When a moderator steps down or is removed from your team, you must immediately revoke their access to the Modmail bot commands, the database, and the log viewer. If you fail to do so: you are violating this privacy policy, which could carry civil penalties in some jurisdictions. + +5. Regional Privacy Laws + +> Depending on where you and your users reside, you may be subject to strict data protection laws like the GDPR in Europe or the CCPA in California. These laws impose significant obligations regarding data handling, consent, and user rights, even for hobbyist or volunteer run Discord servers. +{% endhint %} \ No newline at end of file diff --git a/frequently-asked-questions.md b/frequently-asked-questions.md index 5c776c9..d641167 100644 --- a/frequently-asked-questions.md +++ b/frequently-asked-questions.md @@ -4,7 +4,90 @@ description: A list of commonly asked questions or problems related to Modmail. # Frequently Asked Questions -### I tried installing the dependencies with another Python version and it messed up my Pipfile! How can I get the original Pipfile back? +#### What is Modmail? + +Modmail is a Discord bot, similar to Reddit's Modmail feature. It serves as a shared inbox for server staff to communicate with their users - and vice versa - in a seamless way. + +#### Can I invite Modmail? + +Unfortunately, due to the nature of the bot, there is not a global invite link. Nonetheless, you can obtain a free copy of Modmail for your server. Follow the official tutorial at [https://docs.modmail.dev/installation](https://docs.modmail.dev/installation). However, if you don’t want the hassle of installing and maintaining Modmail, we offer installation, hosting, and other cool perks for [subscribers](https://buymeacoffee.com/modmaildev). + +#### How does Modmail work? + +Modmail uses the Discord API to interact with the platform. When someone sends a DM to the bot, it will create a new thread. Members of the moderation team can help the user and once the conversation ended, you will have access to a beautiful log of it online. + +#### Is Modmail safe? + +Your Modmail bot is safe as long as you don't share your bot's token or the mongodb connection_uri. If you share your token, a "hacker" can take control over your bot and the connection_uri would give them access to all stored modmail data. If you shared your bot token or connection_uri by mistake, regenerate a new token via the Discord Developer Portal and/or the MongoDB Atlas Dashboard. + +#### Where is my data stored? + +All your data including settings, blocked users, logs, installed plugins etc. are stored in your MongoDB database. The bot files only contain the stuff needed to run the bot. This means you can move your bot to a different host and still have your data intact, as long as you use the same MongoDB URI. + +#### Can I request new features? + +Modmail is an open-source project, which means you can easily add or request new features. You can make an issue or submit a pull request to the development branch on the repository. [Check out the contribution guidelines.](https://github.com/modmail-dev/modmail/blob/master/CONTRIBUTING.md) + +#### How do I become a support member? + +To join our support team, join our [Discord server](https://discord.gg/zmdYe3ZVHG). One of the more experienced members will hold an interview to check if you fit the requirements. + +#### Can I add commands to the bot? + +You can add commands to the bot by using plugins. All currently approved plugins can be found in the `?plugin registry` command. If there is no plugin that fits your desired features you can develop your own plugin, read more about that in the [plugin usage guide](./usage-guide/plugins.md). + +#### My bot is offline, what do I do? + +Join our [Discord server](https://discord.gg/zmdYe3ZVHG) and create a post in the "help-me" forum or DM Modmail. One of our support members will assist you and help you fix the issue. +Please make sure that you provide the hosting method you use to run modmail and the console logs of your bot (if possible). If the bot appears online again automatically at the same time you can also use `?debug hastebin` (share the link) and let us check why the bot had issues. + +#### How can I donate the developers? + +You can support the developers on the [Buy me a coffee page](https://buymeacoffee.com/modmaildev). You will also receive various rewards for it. + +#### I would like to have threads in a seperate guild inbox, how can I do that? + +If you want to use a separate server to the main one as the inbox server (Where threads get relayed to) add the following environment variables into your ``.env`` file: + +* `MODMAIL_GUILD_ID` (the server where messages are sent to) +* `GUILD_ID` (The server where users message from) + +{% hint style="info" %} +You can only use one ID for each of these two variables. It´s not supported for more multi-guild setups. +The `MODMAIL_GUILD_ID` is optional if the GUILD_ID is the inbox server. +{% endhint %} + +#### How do I assign permissions to my staff members to let them reply to threads? + +In order to assign permissions to staff, you need to use the `?permissions add` command. +The basic permission level for replying, managing snippets (pre-defined responses) is the `Supporter` level 2. For a common setup, you can assign this level to your staff role. +An example command to add the permissions to a role would look like this: +``` +?permissions add level 2 @role OR the role ID +``` +(you can repeat this command for adding multiple roles). + +{% hint style="info" %} +If the bot does not automatically add the permissions to the set main category +please check that your Modmail bot has enough permissions to view and edit the category. +{% endhint %} + +For detailed permission setup, please take a look at the [permissions usage guide](./usage-guide/permissions.md) + +#### Does anyone get any info when I create my own modmail? + +There is not much information we get about your instance of modmail, The only thing what we recieve is the guild-info, For example: The guildname, The amount of members of the guild, the botname, and the bot-owner. Using this we keep track of how many Modmail-instances get created on a monthly/yearly base. ( Only modmail-developers can see this ) +You can disable this by adding `DATA_COLLECTION=no` to your `.env` file. +*** + +#### Discord forces me to apply for priviliged Intents to continue using Modmail, why? What does this mean? (Affects large Discord communities only) + +Discord requires bot owners to apply for the usage of priviliged Intents that Modmail uses to offer several functionalities **if your Modmail Bot reaches more than 10,000 Users in total in your server(s)** regardless of the server count. If your bot reaches that user count you need to apply for these intents in the Discord Developer Portal. Official information can be read [here](https://support-dev.discord.com/hc/de/articles/40281523410967-Changes-to-Privileged-Intent-Access-for-Discord-Apps) + +If you need any assistance to fill out the intents application form +regarding what information to sent to Discord please reach out to us in our support server. + +#### I tried installing the dependencies with another Python version and it messed up my Pipfile! How can I get the original Pipfile back? First remove the broken `Pipfile` and `Pipfile.lock` with: @@ -24,9 +107,6 @@ And then, fetch the original files with: git checkout FETCH_HEAD -- Pipfile && git checkout FETCH_HEAD -- Pipfile.lock ``` -### I would like to have threads in a seperate guild inbox, how can I do that? - -If you want to use a separate server to the main one as the inbox server (Where threads get relayed to) add the following environment variables into your ``.env`` file: +#### Answer not found? -* `MODMAIL_GUILD_ID` (the server where messages are sent to) -* `GUILD_ID` (The server where users message from) +Feel free to join our [Discord server](https://discord.gg/zmdYe3ZVHG). People will gladly help you with any questions that you have! Just create a post in the "help-me" forum or DM our Modmail. \ No newline at end of file