diff --git a/docs/content/.vuepress/config.js b/docs/content/.vuepress/config.js index b7000005..abd2de20 100644 --- a/docs/content/.vuepress/config.js +++ b/docs/content/.vuepress/config.js @@ -46,6 +46,17 @@ module.exports = { "/tips-and-tricks" ] }, + { + title: "For server staff", + collapsable: false, + children: [ + "/staff/permissions", + "/staff/moderation", + "/staff/disabling", + "/staff/logging", + "/staff/compatibility", + ] + }, ["https://discord.gg/PczBt78", "Join the support server"], ] }, diff --git a/docs/content/assets/log_example.png b/docs/content/assets/log_example.png new file mode 100644 index 00000000..205833f5 Binary files /dev/null and b/docs/content/assets/log_example.png differ diff --git a/docs/content/command-list.md b/docs/content/command-list.md index efb9b18a..d6cc2828 100644 --- a/docs/content/command-list.md +++ b/docs/content/command-list.md @@ -68,7 +68,7 @@ Words in **\** or **[square brackets]** mean fill-in-the-blank. - `pk;log channel ` - Sets the given channel to log all proxied messages. - `pk;log disable <#channel> [#channel...]` - Disables logging messages posted in the given channel(s) (useful for staff channels and such). - `pk;log enable <#channel> [#channel...]` - Re-enables logging messages posted in the given channel(s). -- `pk;logclean ` - Enables or disables [log cleanup](/guide#log-cleanup). +- `pk;logclean ` - Enables or disables [log cleanup](./staff/compatibility.md#log-cleanup). - `pk;blacklist add <#channel> [#channel...]` - Adds the given channel(s) to the proxy blacklist (proxying will be disabled here) - `pk;blacklist remove <#channel> [#channel...]` - Removes the given channel(s) from the proxy blacklist. @@ -77,16 +77,16 @@ Words in **\** or **[square brackets]** mean fill-in-the-blank. - `pk;invite` - Sends the bot invite link for PluralKit. - `pk;import` - Imports a data file from PluralKit or Tupperbox. - `pk;export` - Exports a data file containing your system information. -- `pk;permcheck [server id]` - [Checks the given server's permission setup](/tips#permission-checker-command) to check if it's compatible with PluralKit. +- `pk;permcheck [server id]` - [Checks the given server's permission setup](./staff/permissions.md#permission-checker-command) to check if it's compatible with PluralKit. ## API -*(for using the [PluralKit API](/api), useful for developers)* +*(for using the [PluralKit API](./api-documentation.md), useful for developers)* - `pk;token` - DMs you a token for using the PluralKit API. - `pk;token refresh` - Refreshes your API token and invalidates the old one. ## Help - `pk;help` - Displays a basic help message describing how to use the bot. -- `pk;help proxy` - Directs you to [this page](/guide#proxying). +- `pk;help proxy` - Directs you to [this page](./user-guide.md#proxying). - `pk;system help` - Lists system-related commands. - `pk;member help` - Lists member-related commands. - `pk;switch help` - Lists switch-related commands. diff --git a/docs/content/staff/compatibility.md b/docs/content/staff/compatibility.md new file mode 100644 index 00000000..758dfa06 --- /dev/null +++ b/docs/content/staff/compatibility.md @@ -0,0 +1,43 @@ +# Compatibility with other bots +Many servers use *logger bots* for keeping track of edited and deleted messages, nickname changes, and other server events. +Because PluralKit deletes messages as part of proxying, this can often clutter up these logs. + +## Bots with PluralKit support +Some logger bots have offical PluralKit support, and properly handle excluding proxy deletes, as well as add PK-specific information to relevant log messages: + +- [**Gabby Gums**](https://github.com/amadea-system/GabbyGums) + +If your server uses an in-house bot for logging, you can use [the API](../api-documentation.md) to implement support yourself. + +## Log cleanup +Another solution is for PluralKit to automatically delete log messages from other bots when they get posted. +PluralKit supports this through the **log cleanup** feature. To enable it, use the following command: + + pk;logclean on + +This requires you to have the *Manage Server* permission on the server. + +### Supported bots +At the moment, log cleanup works with the following bots: +- [Auttaja](https://auttaja.io/) (precise) +- [blargbot](https://blargbot.xyz/) (precise) +- [Carl-bot](https://carl.gg/) (fuzzy) +- [Circle](https://circlebot.xyz/) (fuzzy) +- [Dyno](https://dyno.gg/) (precise) +- [GearBot](https://gearbot.rocks/) (fuzzy) +- [GenericBot](https://github.com/galenguyer/GenericBot) (precise) +- [Logger#6088](https://logger.bot/) (precise) +- [Logger#6278](https://loggerbot.chat/) (precise) +- [Mantaro](https://mantaro.site/) (precise) +- [Pancake](https://pancake.gg/) (fuzzy) +- [SafetyAtLast](https://www.safetyatlast.net/) (fuzzy) +- [UnbelievaBoat](https://unbelievaboat.com/) (precise) +- Vanessa (fuzzy) + +::: warning +In most cases, PluralKit will match log messages by the ID of the deleted message itself. However, some bots (marked with *(fuzzy)* above) don't include this in their logs. In this case, PluralKit will attempt to match based on other parameters, but there may be false positives. + +**For best results, use a bot marked *(precise)* in the above list.** +::: + +If you want support for another logging bot, [let me know on the support server](https://discord.gg/PczBt78). \ No newline at end of file diff --git a/docs/content/staff/disabling.md b/docs/content/staff/disabling.md new file mode 100644 index 00000000..2e5b62f4 --- /dev/null +++ b/docs/content/staff/disabling.md @@ -0,0 +1,9 @@ +# Disabling proxying in a channel +It's possible to block a channel from being used for proxying. To do so, use the `pk;blacklist` command. For example: + + pk;blacklist add #admin-channel #mod-channel #welcome + pk;blacklist add all + pk;blacklist remove #general-two + pk;blacklist remove all + +This requires you to have the *Manage Server* permission on the server. \ No newline at end of file diff --git a/docs/content/staff/logging.md b/docs/content/staff/logging.md new file mode 100644 index 00000000..673f5766 --- /dev/null +++ b/docs/content/staff/logging.md @@ -0,0 +1,18 @@ +# Proxy logging +If you want to log every proxied message to a separate channel for moderation purposes, you can use the `pk;log` command with the channel name.For example: + + pk;log #proxy-log + +This requires you to have the *Manage Server* permission on the server. To disable logging, use the `pk;log` command with no channel name. + +Log messages have the following format: + +![Example log message from PluralKit](../assets/log_example.png) + +## Blacklisting channels from logging +Depending on your server setup, you may want to exclude some messages from logging. For example, if you have public proxy logs, you may want to exclude staff-only channels. + +To manage logging in a channel, use the following commands: + + pk;log disable #some-secret-channel + pk;log enable #some-secret-channel \ No newline at end of file diff --git a/docs/content/staff/moderation.md b/docs/content/staff/moderation.md new file mode 100644 index 00000000..8966ee47 --- /dev/null +++ b/docs/content/staff/moderation.md @@ -0,0 +1,34 @@ +# Moderation tools +Since PluralKit proxies work by deleting and reposting messages through webhooks, some of Discord's standard moderation tools won't function. + +Specifically, you can't kick or ban individual members of a system; all moderation actions have to be taken on the concrete Discord account. + +## Identifying users +You can use PluralKit's lookup tools to connect a message to the sender account. This allows you to use standard moderation tools on that account (kicking, banning, using other moderation tools, etc). + +### Querying messages +To look up which account's behind a given message (as well as other information), you can either: + +- React to the message with the :question: emoji, which will DM you a message card +- Use the `pk;msg ` command with the message's link, which will reply with a message card *(this also works in PluralKit's DMs)* + +An example of a message card is seen below: + +![Example of a message query card](../assets/ExampleQuery.png) + +### Looking up systems and accounts +Looking up a system by its 5-character ID (`exmpl` in the above screenshot) will show you a list of its linked account IDs. For example: + + pk;system exmpl + +You can also do the reverse operation by passing a Discord account ID (or a @mention), like so: + + pk;system 466378653216014359 + +Both commands output a system card, which includes a linked account list. These commands also work in PluralKit's DMs. + +### System tags +A common rule on servers with PluralKit is to enforce system tags. System tags are a little snippet of text, a symbol, an emoji, etc, that's added to the webhook name of every message proxied by a system. A system tag will allow you to identify members that share a system at a glance. Note that this isn't enforced by the bot; this is simply a suggestion for a helpful server policy :slightly_smiling_face: + +## Blocking users +It's not possible to block specific PluralKit users. Discord webhooks don't count as 'real accounts', so there's no way to block them. PluralKit also can't control who gets to see a message, so there's also no way to implement user blocking on the bot's end. Sorry. :slightly_frowning_face: \ No newline at end of file diff --git a/docs/content/staff/permissions.md b/docs/content/staff/permissions.md new file mode 100644 index 00000000..0a6a14c0 --- /dev/null +++ b/docs/content/staff/permissions.md @@ -0,0 +1,31 @@ +# Roles and permissions + +PluralKit requires some channel permissions in order to function properly: + +- Message proxying requires the **Manage Messages** and **Manage Webhooks** permissions in a channel. +- Most commands require the **Embed Links**, **Attach Files** and **Add Reactions** permissions to function properly. + - Commands with reaction menus also require **Manage Messages** to remove reactions after clicking. +- [Proxy logging](./logging.md) requires the **Send Messages** permission in the log channel. +- [Log cleanup](./compatibility.md#log-cleanup) requires the **Manage Messages** permission in the log channels. + +Denying the **Send Messages** permission will *not* stop the bot from proxying, although it will prevent it from sending command responses. Denying the **Read Messages** permission will, as any other bot, prevent the bot from interacting in that channel at all. + +## Webhook permissions +Webhooks exist outside of the normal Discord permissions system, and (with a few exceptions) it's not possible to modify their permissions. + +However, PluralKit will make an attempt to apply the sender account's permissions to proxied messages. For example, role mentions, `@everyone`, and `@here` +will only function if the sender account has that permission. The same applies to link embeds. + +## Troubleshooting + +### Permission checker command +To quickly check if PluralKit is missing channel permissions, you can use the `pk;permcheck` command in the server +in question. It'll return a list of channels on the server with missing permissions. This may include channels +you don't want PluralKit to have access to for one reason or another (eg. admin channels). + +If you want to check permissions in DMs, you'll need to add a server ID, and run the command with that. +For example: + + pk;permcheck 466707357099884544 + +You can find this ID [by enabling Developer Mode and right-clicking (or long-pressing) on the server icon](https://discordia.me/developer-mode). \ No newline at end of file diff --git a/docs/content/tips-and-tricks.md b/docs/content/tips-and-tricks.md index 74b5e00b..03dcfd15 100644 --- a/docs/content/tips-and-tricks.md +++ b/docs/content/tips-and-tricks.md @@ -24,16 +24,4 @@ PluralKit has a couple of useful command shorthands to reduce the typing: |pk;member new|pk;m n| |pk;switch|pk;sw| |pk;message|pk;msg| -|pk;autoproxy|pk;ap| - -## Permission checker command -If you're having issues with PluralKit not proxying, it may be an issue with your server's channel permission setup. -PluralKit needs the *Read Messages*, *Manage Messages* and *Manage Webhooks* permission to function. - -To quickly check if PluralKit is missing channel permissions, you can use the `pk;permcheck` command in the server -in question. It'll return a list of channels on the server with missing permissions. This may include channels -you don't want PluralKit to have access to for one reason or another (eg. admin channels). - -If you want to check permissions in DMs, you'll need to add a server ID, and run the command with that. -For example: `pk;permcheck 466707357099884544`. You can find this ID -[by enabling Developer Mode and right-clicking (or long-pressing) on the server icon](https://discordia.me/developer-mode). \ No newline at end of file +|pk;autoproxy|pk;ap| \ No newline at end of file diff --git a/docs/content/user-guide.md b/docs/content/user-guide.md index e1db6995..65644b18 100644 --- a/docs/content/user-guide.md +++ b/docs/content/user-guide.md @@ -473,49 +473,6 @@ For example: pk;member Robert privacy birthday public pk;member Skyler privacy all private -## Moderation commands - -### Log channel -If you want to log every proxied message to a separate channel for moderation purposes, you can use the `pk;log` command with the channel name. -This requires you to have the *Manage Server* permission on the server. For example: - - pk;log #proxy-log - -To disable logging, use the `pk;log` command with no channel name. - -### Channel blacklisting -It's possible to blacklist a channel from being used for proxying. To do so, use the `pk;blacklist` command, for examplle: - - pk;blacklist add #admin-channel #mod-channel #welcome - pk;blacklist add all - pk;blacklist remove #general-two - pk;blacklist remove all - -This requires you to have the *Manage Server* permission on the server. - -### Log cleanup -Many servers use *logger bots* for keeping track of edited and deleted messages, nickname changes, and other server events. Because -PluralKit deletes messages as part of proxying, this can often clutter up these logs. To remedy this, PluralKit can delete those -log messages from the logger bots. To enable this, use the following command: - - pk;logclean on - -This requires you to have the *Manage Server* permission on the server. At the moment, log cleanup works with the following bots: -- Auttaja -- blargbot -- Carl-bot -- Circle -- Dyno -- GenericBot -- Logger (#6088 and #6278) -- Mantaro -- Pancake -- UnbelievaBoat - -If you want support for another logging bot, [let me know on the support server](https://discord.gg/PczBt78). - -Another alternative is to use the **Gabby Gums** logging bot - an invite link for which can be found [on Gabby Gums' support server](https://discord.gg/Xwhk89T). - ## Importing and exporting data If you're a user of another proxy bot (eg. Tupperbox), or you want to import a saved system backup, you can use the importing and exporting commands.