Migrate docs to Vuepress
65
docs/content/.vuepress/config.js
Normal file
@@ -0,0 +1,65 @@
|
||||
module.exports = {
|
||||
title: 'PluralKit',
|
||||
|
||||
base: "/",
|
||||
head: [
|
||||
["link", { rel: "icon", type: "image/png", href: "/favicon.png" }],
|
||||
['meta', { name: 'theme-color', content: '#da9317' }],
|
||||
['meta', { name: 'apple-mobile-web-app-capable', content: 'yes' }],
|
||||
['meta', { name: 'apple-mobile-web-app-status-bar-style', content: 'black' }]
|
||||
],
|
||||
evergreen: true,
|
||||
|
||||
markdown: {
|
||||
extendMarkdown: md => {
|
||||
md.use(require("markdown-it-custom-header-link"));
|
||||
md.use(require("markdown-it-imsize"));
|
||||
}
|
||||
},
|
||||
|
||||
themeConfig: {
|
||||
repo: 'xSke/PluralKit',
|
||||
docsDir: 'docs',
|
||||
docsBranch: 'main',
|
||||
editLinks: true,
|
||||
editLinkText: 'Help us improve this page!',
|
||||
lastUpdated: "Last updated",
|
||||
nextLinks: false,
|
||||
prevLinks: false,
|
||||
nav: [
|
||||
{ text: "Support server", link: "https://discord.gg/PczBt78" },
|
||||
{ text: "Invite bot", link: "https://discord.com/oauth2/authorize?client_id=466378653216014359&scope=bot&permissions=536995904" }
|
||||
],
|
||||
sidebar: [
|
||||
"/",
|
||||
{
|
||||
title: "Documentation",
|
||||
collapsable: false,
|
||||
sidebarDepth: 2,
|
||||
children: [
|
||||
"/getting-started",
|
||||
"/user-guide",
|
||||
"/command-list",
|
||||
"/api-documentation",
|
||||
"/privacy-policy",
|
||||
"/faq",
|
||||
"/tips-and-tricks"
|
||||
]
|
||||
},
|
||||
["https://discord.gg/PczBt78", "Join the support server"],
|
||||
["https://discord.com/oauth2/authorize?client_id=466378653216014359&scope=bot&permissions=536995904", "Add to your server"],
|
||||
]
|
||||
},
|
||||
|
||||
plugins: [
|
||||
'@vuepress/plugin-back-to-top',
|
||||
'@vuepress/plugin-medium-zoom',
|
||||
[
|
||||
'@vuepress/google-analytics',
|
||||
{
|
||||
"ga": "UA-173942267-1"
|
||||
}
|
||||
],
|
||||
["vuepress-plugin-clean-urls", { normalSuffix: "/" }],
|
||||
],
|
||||
}
|
BIN
docs/content/.vuepress/public/favicon.png
Normal file
After Width: | Height: | Size: 20 KiB |
7
docs/content/.vuepress/styles/index.styl
Normal file
@@ -0,0 +1,7 @@
|
||||
// For custom styles
|
||||
// See: https://vuepress.vuejs.org/config/#index-styl
|
||||
|
||||
// Center images on page (only relevant when resized with markdown-it-imsize)
|
||||
img
|
||||
display block
|
||||
margin auto
|
7
docs/content/.vuepress/styles/palette.styl
Normal file
@@ -0,0 +1,7 @@
|
||||
// Global variables go here, no styles! Some override default theme parameters.
|
||||
// See: https://vuepress.vuejs.org/config/#palette-styl
|
||||
|
||||
$accentColor = #da9317
|
||||
|
||||
// Make page slightly wider (default is 740px)
|
||||
$contentWidth = 900px
|
545
docs/content/api-documentation.md
Normal file
@@ -0,0 +1,545 @@
|
||||
---
|
||||
title: API documentation
|
||||
description: PluralKit's API documentation.
|
||||
permalink: /api
|
||||
---
|
||||
|
||||
**2020-05-07**: The PluralKit API is now documented on Swagger: https://app.swaggerhub.com/apis-docs/xSke/PluralKit/1.1
|
||||
Accompanying it is an [OpenAPI v3.0 definition](https://github.com/xSke/PluralKit/blob/master/PluralKit.API/openapi.yaml). It's mostly complete, but is still subject to change - so don't go generating API clients and mock servers with it quite yet. It may still be useful, though :)
|
||||
|
||||
# API documentation
|
||||
|
||||
PluralKit has a basic HTTP REST API for querying and modifying your system.
|
||||
The root endpoint of the API is `https://api.pluralkit.me/v1/`.
|
||||
|
||||
Endpoints will always return all fields, using `null` when a value is missing. On `PATCH` endpoints,
|
||||
missing fields from the JSON request will be ignored and preserved as is, but on `POST` endpoints will
|
||||
be set to `null` or cleared.
|
||||
|
||||
Endpoints taking JSON bodies (eg. most `PATCH` and `PUT` endpoints) require the `Content-Type: application/json` header set.
|
||||
|
||||
## Authentication
|
||||
Authentication is done with a simple "system token". You can get your system token by running `pk;token` using the
|
||||
Discord bot, either in a channel with the bot or in DMs. Then, pass this token in the `Authorization` HTTP header
|
||||
on requests that require it. Failure to do so on endpoints that require authentication will return a `401 Unauthorized`.
|
||||
|
||||
Some endpoints show information that a given system may have set to private. If this is a specific field
|
||||
(eg. description), the field will simply contain `null` rather than the true value. If this applies to entire endpoint
|
||||
responses (eg. fronter, switches, member list), the entire request will return `403 Forbidden`. Authenticating with the
|
||||
system's token (as described above) will override these privacy settings and show the full information.
|
||||
|
||||
## Models
|
||||
The following three models (usually represented in JSON format) represent the various objects in PluralKit's API. A `?` after the column type indicates an optional (nullable) parameter.
|
||||
|
||||
### System model
|
||||
|
||||
| Key | Type | Patchable? | Notes |
|
||||
| --------------------- | -------- | ---------- | ----------------------------------------------------------------------------------------- |
|
||||
| id | string | No | |
|
||||
| name | string? | Yes | 100-character limit. |
|
||||
| description | string? | Yes | 1000-character limit. |
|
||||
| tag | string? | Yes | |
|
||||
| avatar_url | url? | Yes | Not validated server-side. |
|
||||
| tz | string? | Yes | Tzdb identifier. Patching with `null` will store `"UTC"`. |
|
||||
| created | datetime | No | |
|
||||
| description_privacy | string? | Yes | Patching with `private` will set it to private; `public` or `null` will set it to public. |
|
||||
| member_list_privacy | string? | Yes | Same as above. |
|
||||
| front_privacy | string? | Yes | Same as above. |
|
||||
| front_history_privacy | string? | Yes | Same as above. |
|
||||
|
||||
### Member model
|
||||
|
||||
| Key | Type | Patchable? | Notes |
|
||||
| ------------------- | ---------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| id | string | No | |
|
||||
| name | string? | Yes | 50-character limit. |
|
||||
| display_name | string? | Yes | 50-character limit. |
|
||||
| description | string? | Yes | 1000-character limit. |
|
||||
| color | color? | Yes | 6-char hex (eg. `ff7000`), sans `#`. |
|
||||
| avatar_url | url? | Yes | Not validated server-side. |
|
||||
| birthday | date? | Yes | ISO-8601 (`YYYY-MM-DD`) format, year of `0001` or `0004` means hidden year. Birthdays set after 2020-02-10 use `0004` as a sentinel year, but both options are recognized as valid. |
|
||||
| prefix | string? | Yes | **Deprecated.** Use `proxy_tags` instead. |
|
||||
| suffix | string? | Yes | **Deprecated.** Use `proxy_tags` instead. |
|
||||
| proxy_tags | ProxyTag[] | Yes (entire array) | An array of ProxyTag (see below) objects, each representing a single prefix/suffix pair. |
|
||||
| keep_proxy | bool | Yes | Whether to display a member's proxy tags in the proxied message. |
|
||||
| created | datetime | No |
|
||||
| privacy | string? | Yes | **Deprecated.** Use `<subject>_privacy` and `visibility` fields. |
|
||||
| visibility | string? | Yes | Patching with `private` will set it to private; `public` or `null` will set it to public. |
|
||||
| name_privacy | string? | Yes | Patching with `private` will set it to private; `public` or `null` will set it to public. |
|
||||
| description_privacy | string? | Yes | Patching with `private` will set it to private; `public` or `null` will set it to public. |
|
||||
| avatar_privacy | string? | Yes | Patching with `private` will set it to private; `public` or `null` will set it to public. |
|
||||
| birthday_privacy | string? | Yes | Patching with `private` will set it to private; `public` or `null` will set it to public. |
|
||||
| pronoun_privacy | string? | Yes | Patching with `private` will set it to private; `public` or `null` will set it to public. |
|
||||
| metadata_privacy | string? | Yes | Patching with `private` will set it to private; `public` or `null` will set it to public. |
|
||||
|
||||
#### ProxyTag object
|
||||
|
||||
| Key | Type |
|
||||
| ------ | ------- |
|
||||
| prefix | string? |
|
||||
| suffix | string? |
|
||||
|
||||
### Switch model
|
||||
|
||||
| Key | Type | Notes |
|
||||
| --------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| timestamp | datetime | |
|
||||
| members | list of id/Member | Is sometimes in plain ID list form (eg. `GET /s/<id>/switches`), sometimes includes the full Member model (eg. `GET /s/<id>/fronters`). |
|
||||
|
||||
### Message model
|
||||
|
||||
| Key | Type | Notes |
|
||||
| --------- | ------------------ | ------------------------------------------------------------------------------------------------------ |
|
||||
| timestamp | datetime | |
|
||||
| id | snowflake | The ID of the message sent by the webhook. Encoded as string for precision reasons. |
|
||||
| original | snowflake | The ID of the (now-deleted) message that triggered the proxy. Encoded as string for precision reasons. |
|
||||
| sender | snowflake | The user ID of the account that triggered the proxy. Encoded as string for precision reasons. |
|
||||
| channel | snowflake | The ID of the channel the message was sent in. Encoded as string for precision reasons. |
|
||||
| system | full System object | The system that proxied the message. |
|
||||
| member | full Member object | The member that proxied the message. |
|
||||
|
||||
## Endpoints
|
||||
|
||||
### GET /s
|
||||
**Requires authentication.**
|
||||
|
||||
Returns information about your own system.
|
||||
|
||||
#### Example request
|
||||
GET https://api.pluralkit.me/v1/s
|
||||
|
||||
#### Example response
|
||||
```json
|
||||
{
|
||||
"id": "abcde",
|
||||
"name": "My System",
|
||||
"description": "This is my system description. Yay.",
|
||||
"tag": "[MySys]",
|
||||
"avatar_url": "https://path/to/avatar/image.png",
|
||||
"tz": "Europe/Copenhagen",
|
||||
"created": "2019-01-01T14:30:00.987654Z",
|
||||
"description_privacy": "private",
|
||||
"member_list_privacy": "public",
|
||||
"front_privacy": "public",
|
||||
"front_history_privacy": "private"
|
||||
}
|
||||
```
|
||||
|
||||
### GET /s/:id
|
||||
Queries a system by its 5-character ID, and returns information about it. If the system doesn't exist, returns `404 Not Found`.
|
||||
Some fields may be set to `null` if unauthenticated and the system has chosen to make those fields private.
|
||||
|
||||
#### Example request
|
||||
GET https://api.pluralkit.me/v1/s/abcde
|
||||
|
||||
#### Example response
|
||||
```json
|
||||
{
|
||||
"id": "abcde",
|
||||
"name": "My System",
|
||||
"description": "This is my system description. Yay.",
|
||||
"tag": "[MySys]",
|
||||
"avatar_url": "https://path/to/avatar/image.png",
|
||||
"tz": "Europe/Copenhagen",
|
||||
"created": "2019-01-01T14:30:00.987654Z",
|
||||
"description_privacy": null,
|
||||
"member_list_privacy": null,
|
||||
"front_privacy": null,
|
||||
"front_history_privacy": null
|
||||
}
|
||||
```
|
||||
|
||||
### GET /s/:id/members
|
||||
Queries a system's member list by its 5-character ID. If the system doesn't exist, returns `404 Not Found`.
|
||||
If the system has chosen to hide its member list, this will return `403 Forbidden`, unless the request is authenticated with the system's token.
|
||||
If the request is not authenticated with the system's token, members marked as private will *not* be returned.
|
||||
|
||||
#### Example request
|
||||
GET https://api.pluralkit.me/v1/s/abcde/members
|
||||
|
||||
#### Example response
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "qwert",
|
||||
"name": "Craig Johnson",
|
||||
"color": "ff7000",
|
||||
"avatar_url": "https://path/to/avatar/image.png",
|
||||
"birthday": "1997-07-14",
|
||||
"pronouns": "he/him or they/them",
|
||||
"description": "I am Craig, example user extraordinaire.",
|
||||
"proxy_tags": [{"prefix": "[", "suffix": "]"}],
|
||||
"keep_proxy": false,
|
||||
"created": "2019-01-01T15:00:00.654321Z",
|
||||
"visibility": null,
|
||||
"name_privacy": null,
|
||||
"description_privacy": null,
|
||||
"birthday_privacy": null,
|
||||
"pronoun_privacy": null,
|
||||
"metadata_privacy": null
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### GET /s/:id/switches
|
||||
Returns a system's switch history in newest-first chronological order, with a maximum of 100 switches. If the system doesn't exist, returns `404 Not Found`.
|
||||
Optionally takes a `?before=` query parameter with an ISO-8601-formatted timestamp, and will only return switches
|
||||
that happen before that timestamp.
|
||||
|
||||
If the system has chosen to hide its switch history, this will return `403 Forbidden`, unless the request is authenticated with the system's token.
|
||||
|
||||
#### Example request
|
||||
GET https://api.pluralkit.me/v1/s/abcde/switches?before=2019-03-01T14:00:00Z
|
||||
|
||||
#### Example response
|
||||
```json
|
||||
[
|
||||
{
|
||||
"timestamp": "2019-02-23T14:20:59.123456Z",
|
||||
"members": ["qwert", "yuiop"]
|
||||
},
|
||||
{
|
||||
"timestamp": "2019-02-22T12:00:00Z",
|
||||
"members": ["yuiop"]
|
||||
},
|
||||
{
|
||||
"timestamp": "2019-02-20T09:30:00Z",
|
||||
"members": []
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### GET /s/:id/fronters
|
||||
Returns a system's current fronter(s), with fully hydrated member objects. If the system doesn't exist, *or* the system has no registered switches, returns `404 Not Found`.
|
||||
If the system has chosen to hide its current fronters, this will return `403 Forbidden`, unless the request is authenticated with the system's token. If a returned member is private, and the request isn't properly authenticated, some fields may be null.
|
||||
|
||||
#### Example request
|
||||
GET https://api.pluralkit.me/v1/s/abcde/fronters
|
||||
|
||||
#### Example response
|
||||
```json
|
||||
{
|
||||
"timestamp": "2019-07-09T17:22:46.47441Z",
|
||||
"members": [
|
||||
{
|
||||
"id": "qwert",
|
||||
"name": "Craig Johnson",
|
||||
"color": "ff7000",
|
||||
"avatar_url": "https://path/to/avatar/image.png",
|
||||
"birthday": "1997-07-14",
|
||||
"pronouns": "he/him or they/them",
|
||||
"description": "I am Craig, example user extraordinaire.",
|
||||
"proxy_tags": [{"prefix": "[", "suffix": "]"}],
|
||||
"keep_proxy": false,
|
||||
"visibility": null,
|
||||
"name_privacy": null,
|
||||
"description_privacy": null,
|
||||
"avatar_privacy": null,
|
||||
"birthday_privacy": null,
|
||||
"pronoun_privacy": null,
|
||||
"metadata_privacy": null,
|
||||
"created": "2019-01-01T15:00:00.654321Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### PATCH /s
|
||||
**Requires authentication.**
|
||||
|
||||
Edits your own system's information. Missing fields will keep their current values. Will return the new system object.
|
||||
|
||||
#### Example request
|
||||
PATCH https://api.pluralkit.me/v1/s
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "New System Name",
|
||||
"tag": "{Sys}",
|
||||
"avatar_url": "https://path/to/new/avatar.png",
|
||||
"tz": "America/New_York",
|
||||
"description_privacy": "private",
|
||||
"member_list_privacy": "public",
|
||||
"front_privacy": "public",
|
||||
"front_history_privacy": "private"
|
||||
}
|
||||
```
|
||||
(note the absence of a `description` field, which has its old value preserved in the response)
|
||||
|
||||
#### Example response
|
||||
```json
|
||||
{
|
||||
"id": "abcde",
|
||||
"name": "New System Name",
|
||||
"description": "The Old Description, Not Updated",
|
||||
"tag": "{Sys}",
|
||||
"avatar_url": "https://path/to/new/avatar.png",
|
||||
"tz": "America/New_York",
|
||||
"created": "2019-01-01T14:30:00.987654Z",
|
||||
"description_privacy": "private",
|
||||
"member_list_privacy": "public",
|
||||
"front_privacy": "public",
|
||||
"front_history_privacy": "private"
|
||||
}
|
||||
```
|
||||
|
||||
### POST /s/switches
|
||||
**Requires authentication.**
|
||||
|
||||
Registers a new switch to your own system given a list of member IDs.
|
||||
|
||||
#### Example request
|
||||
POST https://api.pluralkit.me/v1/s/switches
|
||||
|
||||
```json
|
||||
{
|
||||
"members": ["qwert", "yuiop"]
|
||||
}
|
||||
```
|
||||
|
||||
#### Example response
|
||||
(`204 No Content`)
|
||||
|
||||
### GET /m/:id
|
||||
Queries a member's information by its 5-character member ID. If the member does not exist, will return `404 Not Found`.
|
||||
If this member is marked private, and the request isn't authenticated with the member's system's token, some fields will contain `null` rather than the true value (corresponding with the privacy settings). Regardless of privacy setting, a non-authenticated request will only receive `null` for the privacy fields (and `visibility`).
|
||||
|
||||
#### Example request
|
||||
GET https://api.pluralkit.me/v1/m/qwert
|
||||
|
||||
#### Example response
|
||||
```json
|
||||
{
|
||||
"id": "qwert",
|
||||
"name": "Craig Johnson",
|
||||
"color": "ff7000",
|
||||
"avatar_url": "https://path/to/avatar/image.png",
|
||||
"birthday": "1997-07-14",
|
||||
"pronouns": "he/him or they/them",
|
||||
"description": "I am Craig, example user extraordinaire.",
|
||||
"proxy_tags": [{"prefix": "[", "suffix": "]"}],
|
||||
"keep_proxy": false,
|
||||
"created": "2019-01-01T15:00:00.654321Z",
|
||||
"visibility": "public",
|
||||
"name_privacy": "public",
|
||||
"description_privacy": "private",
|
||||
"avatar_privacy": "private",
|
||||
"birthday_privacy": "private",
|
||||
"pronoun_privacy": "public",
|
||||
"metadata_privacy": "public"
|
||||
}
|
||||
```
|
||||
|
||||
### POST /m
|
||||
**Requires authentication.**
|
||||
|
||||
Creates a new member with the information given. Missing fields (except for name) will be set to `null`. Will return the new member object. Member must (obviously) belong to your own system.
|
||||
|
||||
#### Example request
|
||||
POST https://api.pluralkit.me/v1/m
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Craig Peterson",
|
||||
"display_name": "Craig Peterson [he/they]",
|
||||
"color": null,
|
||||
"avatar_url": "https://path/to/new/image.png",
|
||||
"birthday": "1997-07-14",
|
||||
"pronouns": "they/them",
|
||||
"description": "I am Craig, cooler example user extraordinaire.",
|
||||
"keep_proxy": false,
|
||||
"visibility": "public",
|
||||
"name_privacy": "public",
|
||||
"description_privacy": "private",
|
||||
"avatar_privacy": "private",
|
||||
"birthday_privacy": "private",
|
||||
"pronoun_privacy": "public",
|
||||
"metadata_privacy": "private"
|
||||
}
|
||||
```
|
||||
(note the absence of a `proxy_tags` field, which is cleared in the response)
|
||||
|
||||
#### Example response
|
||||
```json
|
||||
{
|
||||
"id": "qwert",
|
||||
"name": "Craig Peterson",
|
||||
"display_name": "Craig Peterson [he/they]",
|
||||
"color": null,
|
||||
"avatar_url": "https://path/to/new/image.png",
|
||||
"birthday": "1997-07-14",
|
||||
"pronouns": "they/them",
|
||||
"description": "I am Craig, cooler example user extraordinaire.",
|
||||
"proxy_tags": [],
|
||||
"keep_proxy": false,
|
||||
"created": "2019-01-01T15:00:00.654321Z",
|
||||
"visibility": "public",
|
||||
"name_privacy": "public",
|
||||
"description_privacy": "private",
|
||||
"birthday_privacy": "private",
|
||||
"pronoun_privacy": "public",
|
||||
"metadata_privacy": "private"
|
||||
}
|
||||
```
|
||||
|
||||
### PATCH /m/:id
|
||||
**Requires authentication.**
|
||||
|
||||
Edits a member's information. Missing fields will keep their current values. Will return the new member object. Member must (obviously) belong to your own system.
|
||||
|
||||
#### Example request
|
||||
PATCH https://api.pluralkit.me/v1/m/qwert
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Craig Peterson",
|
||||
"display_name": "Craig Peterson [he/they]",
|
||||
"color": null,
|
||||
"avatar_url": "https://path/to/new/image.png",
|
||||
"birthday": "1997-07-14",
|
||||
"pronouns": "they/them",
|
||||
"description": "I am Craig, cooler example user extraordinaire.",
|
||||
"keep_proxy": false,
|
||||
"visibility": "public",
|
||||
"name_privacy": "public",
|
||||
"description_privacy": "private",
|
||||
"avatar_privacy": "private",
|
||||
"birthday_privacy": "private",
|
||||
"pronoun_privacy": "public",
|
||||
"metadata_privacy": "private"
|
||||
}
|
||||
```
|
||||
(note the absence of a `proxy_tags` field, which keeps its old value in the response)
|
||||
|
||||
#### Example response
|
||||
```json
|
||||
{
|
||||
"id": "qwert",
|
||||
"name": "Craig Peterson",
|
||||
"display_name": "Craig Peterson [he/they]",
|
||||
"color": null,
|
||||
"avatar_url": "https://path/to/new/image.png",
|
||||
"birthday": "1997-07-14",
|
||||
"pronouns": "they/them",
|
||||
"description": "I am Craig, cooler example user extraordinaire.",
|
||||
"proxy_tags": [{"prefix": "[", "suffix": "]"}],
|
||||
"keep_proxy": false,
|
||||
"created": "2019-01-01T15:00:00.654321Z",
|
||||
"visibility": "public",
|
||||
"name_privacy": "public",
|
||||
"description_privacy": "private",
|
||||
"avatar_privacy": "private",
|
||||
"birthday_privacy": "private",
|
||||
"pronoun_privacy": "public",
|
||||
"metadata_privacy": "private"
|
||||
}
|
||||
```
|
||||
|
||||
### DELETE /m/:id
|
||||
**Requires authentication.**
|
||||
|
||||
Deletes a member from the database. Be careful as there is no confirmation and the member will be deleted immediately. Member must (obviously) belong to your own system.
|
||||
|
||||
#### Example request
|
||||
DELETE https://api.pluralkit.me/v1/m/qwert
|
||||
|
||||
#### Example response
|
||||
(`204 No Content`)
|
||||
|
||||
### GET /a/:id
|
||||
Queries a system by its linked Discord account ID (17/18-digit numeric snowflake). Returns `404 Not Found` if the account doesn't have a system linked.
|
||||
Some fields may be set to `null` if unauthenticated and the system has chosen to make those fields private.
|
||||
|
||||
#### Example request
|
||||
GET https://api.pluralkit.me/v1/a/466378653216014359
|
||||
|
||||
#### Example response
|
||||
```json
|
||||
{
|
||||
"id": "abcde",
|
||||
"name": "My System",
|
||||
"description": "This is my system description. Yay.",
|
||||
"tag": "[MySys]",
|
||||
"avatar_url": "https://path/to/avatar/image.png",
|
||||
"tz": "Europe/Copenhagen",
|
||||
"created": "2019-01-01T14:30:00.987654Z",
|
||||
"description_privacy": null,
|
||||
"member_list_privacy": null,
|
||||
"front_privacy": null,
|
||||
"front_history_privacy": null
|
||||
}
|
||||
```
|
||||
|
||||
### GET /msg/:id
|
||||
Looks up a proxied message by its message ID. Returns `404 Not Found` if the message ID is invalid or wasn't found (eg. was deleted or not proxied by PK).
|
||||
You can also look messages up by their *trigger* message ID (useful for, say, logging bot integration).
|
||||
|
||||
The returned system and member's privacy settings will be respected, and as such, some fields may be set to null without the proper authentication.
|
||||
|
||||
#### Example request
|
||||
GET https://api.pluralkit.me/v1/msg/601014599386398700
|
||||
|
||||
#### Example response
|
||||
```json
|
||||
{
|
||||
"timestamp": "2019-07-17T11:37:26.805Z",
|
||||
"id": "601014599386398700",
|
||||
"original": "601014598168435600",
|
||||
"sender": "466378653216014359",
|
||||
"channel": "471388251102380000",
|
||||
"system": {
|
||||
"id": "abcde",
|
||||
"name": "My System",
|
||||
"description": "This is my system description. Yay.",
|
||||
"tag": "[MySys]",
|
||||
"avatar_url": "https://path/to/avatar/image.png",
|
||||
"tz": "Europe/Copenhagen",
|
||||
"created": "2019-01-01T14:30:00.987654Z"
|
||||
},
|
||||
"member": {
|
||||
"id": "qwert",
|
||||
"name": "Craig Johnson",
|
||||
"color": "ff7000",
|
||||
"avatar_url": "https://path/to/avatar/image.png",
|
||||
"birthday": "1997-07-14",
|
||||
"pronouns": "he/him or they/them",
|
||||
"description": "I am Craig, example user extraordinaire.",
|
||||
"proxy_tags": [{"prefix": "[", "suffix": "]"}],
|
||||
"keep_proxy": false,
|
||||
"created": "2019-01-01T15:00:00.654321Z",
|
||||
"visibility": "public",
|
||||
"name_privacy": "public",
|
||||
"description_privacy": "private",
|
||||
"avatar_privacy": "private",
|
||||
"birthday_privacy": "private",
|
||||
"pronoun_privacy": "public",
|
||||
"metadata_privacy": "private"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Version history
|
||||
* 2020-06-17 (v1.1)
|
||||
* The API now has values for granular member privacy. The new fields are as follows: `visibility`, `name_privacy`, `description_privacy`, `avatar_privacy`, `birthday_privacy`, `pronoun_privacy`, `metadata_privacy`. All are strings and accept the values of `public`, `private` and `null`.
|
||||
* The `privacy` field has now been deprecated and should not be used. It's still returned (mirroring the `visibility` field), and writing to it will write to *all privacy options*.
|
||||
* 2020-05-07
|
||||
* The API (v1) is now formally(ish) defined with OpenAPI v3.0. [The definition file can be found here.](https://github.com/xSke/PluralKit/blob/master/PluralKit.API/openapi.yaml)
|
||||
* 2020-02-10
|
||||
* Birthdates with no year can now be stored using `0004` as a year, for better leap year support. Both options remain valid and either may be returned by the API.
|
||||
* Added privacy set/get support, meaning you will now see privacy values in authed requests and can set them.
|
||||
* 2020-01-08
|
||||
* Added privacy support, meaning some responses will now lack information or return 403s, depending on the specific system and member's privacy settings.
|
||||
* 2019-12-28
|
||||
* Changed behaviour of missing fields in PATCH responses, will now preserve the old value instead of clearing
|
||||
* This is technically a breaking change, but not *significantly* so, so I won't bump the version number.
|
||||
* 2019-10-31
|
||||
* Added `proxy_tags` field to members
|
||||
* Added `keep_proxy` field to members
|
||||
* Deprecated `prefix` and `suffix` member fields, will be removed at some point (tm)
|
||||
* 2019-07-17
|
||||
* Added endpoint for querying system by account
|
||||
* Added endpoint for querying message contents
|
||||
* 2019-07-10 **(v1)**
|
||||
* First specified version
|
||||
* (prehistory)
|
||||
* Initial release
|
BIN
docs/content/assets/ExampleMember.png
Normal file
After Width: | Height: | Size: 88 KiB |
BIN
docs/content/assets/ExamplePing.png
Normal file
After Width: | Height: | Size: 32 KiB |
BIN
docs/content/assets/ExampleProxy.png
Normal file
After Width: | Height: | Size: 25 KiB |
BIN
docs/content/assets/ExampleQuery.png
Normal file
After Width: | Height: | Size: 38 KiB |
BIN
docs/content/assets/ExampleSystem.png
Normal file
After Width: | Height: | Size: 158 KiB |
BIN
docs/content/assets/demo.gif
Normal file
After Width: | Height: | Size: 70 KiB |
BIN
docs/content/assets/myriad.png
Normal file
After Width: | Height: | Size: 664 KiB |
93
docs/content/command-list.md
Normal file
@@ -0,0 +1,93 @@
|
||||
---
|
||||
layout: default
|
||||
title: Command List
|
||||
permalink: /commands
|
||||
description: The full list of all commands in PluralKit, and a short description of what they do.
|
||||
nav_order: 3
|
||||
---
|
||||
|
||||
# How to read this
|
||||
Words in **\<angle brackets>** or **[square brackets]** mean fill-in-the-blank. Square brackets mean this is optional. Don't include the actual brackets.
|
||||
|
||||
# Commands
|
||||
## System commands
|
||||
*Optionally replace `[system]` with a @mention, Discord account ID, or 5-character ID. For most commands, adding `-clear` will clear/delete the field.*
|
||||
- `pk;system [id]` - Shows information about a system.
|
||||
- `pk;system new [name]` - Creates a new system registered to your account.
|
||||
- `pk;system rename [new name]` - Changes the name of your system.
|
||||
- `pk;system description [description]` - Changes the description of your system.
|
||||
- `pk;system avatar [avatar url]` - Changes the avatar of your system.
|
||||
- `pk;system privacy` - Displays your system's current privacy settings.
|
||||
- `pk;system privacy <subject> <public|private>` - Changes your systems privacy settings.
|
||||
- `pk;system tag [tag]` - Changes the system tag of your system.
|
||||
- `pk;system timezone [location]` - Changes the time zone of your system.
|
||||
- `pk;system proxy [on|off]` - Toggles message proxying for a specific server.
|
||||
- `pk;system delete` - Deletes your system.
|
||||
- `pk;system [system] fronter` - Shows the current fronter of a system.
|
||||
- `pk;system [system] fronthistory` - Shows the last 10 fronters of a system.
|
||||
- `pk;system [system] frontpercent [timeframe]` - Shows the aggregated front history of a system within a given time frame.
|
||||
- `pk;system [system] list` - Shows a paginated list of a system's members.
|
||||
- `pk;system [system] list -full` - Shows a paginated list of a system's members, with increased detail.
|
||||
- `pk;find <search term>` - Searches members by name.
|
||||
- `pk;system [system] find <search term>` - (same as above, but for a specific system)
|
||||
- `pk;autoproxy [off|front|latch|member]` - Updates the system's autoproxy settings for a given server.
|
||||
- `pk;link <account>` - Links this system to a different account.
|
||||
- `pk;unlink [account]` - Unlinks an account from this system.
|
||||
|
||||
## Member commands
|
||||
*Replace `<name>` with a member's name or 5-character ID. For most commands, adding `-clear` will clear/delete the field.*
|
||||
- `pk;member <name>` - Shows information about a member.
|
||||
- `pk;member new <name>` - Creates a new system member.
|
||||
- `pk;member <name> rename <new name>` - Changes the name of a member.
|
||||
- `pk;member <name> displayname <new display name>` - Changes the display name of a member.
|
||||
- `pk;member <name> servername <new server name>` - Changes the display name of a member, only in the current server.
|
||||
- `pk;member <name> description [description]` - Changes the description of a member.
|
||||
- `pk;member <name> avatar <avatar url|@mention>` - Changes the avatar of a member.
|
||||
- `pk;member <name> serveravatar <avatar url|@mention>` - Changes the avatar of a member in a specific server.
|
||||
- `pk;member <name> privacy` - Displays a members current privacy settings.
|
||||
- `pk;member <name> privacy <subject> <public|private>` - Changes a members privacy setting.
|
||||
- `pk;member <name> proxy [tags]` - Changes the proxy tags of a member. use below add/remove commands for members with multiple tag pairs.
|
||||
- `pk;member <name> proxy add [tags]` - Adds a proxy tag pair to a member.
|
||||
- `pk;member <name> proxy remove [tags]` - Removes a proxy tag from a member.
|
||||
- `pk;member <name> keepproxy [on|off]` - Sets whether to include a member's proxy tags in the proxied message.
|
||||
- `pk;member <name> pronouns [pronouns]` - Changes the pronouns of a member.
|
||||
- `pk;member <name> color [color]` - Changes the color of a member.
|
||||
- `pk;member <name> birthdate [birthdate]` - Changes the birthday of a member.
|
||||
- `pk;member <name> delete` - Deletes a member.
|
||||
- `pk;random` - Shows the member card of a randomly selected member in your system.
|
||||
|
||||
## Switching commands
|
||||
- `pk;switch [member...]` - Registers a switch with the given members.
|
||||
- `pk;switch move <time>` - Moves the latest switch backwards in time.
|
||||
- `pk;switch delete` - Deletes the latest switch.
|
||||
- `pk;switch delete all` - Deletes every logged switch.
|
||||
- `pk;switch out` - Registers a 'switch-out' - a switch with no associated members.
|
||||
|
||||
## Server owner commands
|
||||
*(all commands here require Manage Server permission)*
|
||||
- `pk;log channel <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 <on/off>` - Enables or disables [log cleanup](/guide#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.
|
||||
|
||||
## Utility
|
||||
- `pk;message <message id / message link>` - Looks up information about a proxied message by its message ID or link.
|
||||
- `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.
|
||||
|
||||
## API
|
||||
*(for using the [PluralKit API](/api), 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;system help` - Lists system-related commands.
|
||||
- `pk;member help` - Lists member-related commands.
|
||||
- `pk;switch help` - Lists switch-related commands.
|
||||
- `pk;commands` - Directs you to this page!
|
16
docs/content/faq.md
Normal file
@@ -0,0 +1,16 @@
|
||||
---
|
||||
title: FAQ
|
||||
description: Frequently asked questions (and the answers to them).
|
||||
permalink: /faq
|
||||
---
|
||||
|
||||
# Frequently asked questions
|
||||
|
||||
## Can I use this bot for kin/roleplay/other non-plurality uses? Can I use it if I'm not plural myself? Is that appropriating?
|
||||
Although this bot is designed with plural systems and their use cases in mind, the bot's feature set is still useful for many other types of communities, including role-playing and otherkin. By all means go ahead and use it for those communities, too. We don't gatekeep, and neither should you.
|
||||
|
||||
## Who's the mascot?
|
||||
[Our lovely bot mascot](https://imgur.com/a/LTqQHHL)'s name is Myriad! They were drawn by the lovely [Layl](https://twitter.com/braindemons). Yes, there are fictives.
|
||||
|
||||
## How can I support the bot's development?
|
||||
I (the bot author, [Ske](https://twitter.com/floofstrid) have a Patreon. The income from there goes towards server hosting, domains, infrastructure, my Monster Energy addiction, et cetera. There are no benefits. There might never be any. But nevertheless, it can be found here: [https://www.patreon.com/floofstrid](https://www.patreon.com/floofstrid)
|
146
docs/content/getting-started.md
Normal file
@@ -0,0 +1,146 @@
|
||||
---
|
||||
title: Getting Started
|
||||
description: A basic tutorial of how to set up the bot.
|
||||
permalink: /start
|
||||
---
|
||||
|
||||
# Getting Started
|
||||
|
||||
## The system
|
||||
The first thing you need to do to use PluralKit is to set up a system! Each account can have one system, but you can link one system to multiple accounts. To inspect a system, you can pull up its *system card*. Below is an example system with all options set, which you can also see by typing `pk;system exmpl` on Discord:
|
||||
|
||||

|
||||
|
||||
### Parts of the system
|
||||
These are the parts of the system, reading the card top to bottom left to right like a book:
|
||||
1. **System name**: The system name is at the top of the system card. On the example system it is **PluralKit Example System**. System names are optional.
|
||||
2. **Avatar**: This is the system avatar, it is an image that you can put on the system card.
|
||||
3. **Fronters**: This shows who is currently registered as fronting using the [switch tracking commands](/guide#managing-switches). [It can be hidden.](/guide#system-privacy)
|
||||
4. **Tag**: This is the system tag, and it will be placed after the name of members on proxied messages.
|
||||
5. **Members**: This is a member count, and you can use `pk;system list` to see a list of the members.
|
||||
6. **Description**: This is the system description, and can be any text you wish to put on your system card.
|
||||
7. **System ID**: This is the auto-generated ID of the system. You can use this to refer to any system.
|
||||
8. **Created on**: This is the time and date the system was created on.
|
||||
|
||||
### Creating a system
|
||||
You need a system to start creating members, but luckily this is simple! All you need to do is run `pk;system new [name]`. So if you wanted your system to be named "Boxes of Foxes" you would run the command `pk;system new Boxes of Foxes`! If you don't want a name, you can use the command `pk;system new`, with no extra text.
|
||||
If you want to do tweak the system, [see the user guide](/guide#system-management)! This page is just a simple setup guide.
|
||||
|
||||
----
|
||||
|
||||
## Members
|
||||
Once you have created a system, the next thing you need to get started is to create a member! Like before, here is an example of a full member card with all options used:
|
||||
|
||||

|
||||
|
||||
### Parts to a member
|
||||
These are the parts of a member, reading the card top to bottom left to right like a book:
|
||||
1. **Name and system**: This is the name of the member, in this case "Myriad", and the system they are part of in brackets, in this case the "PluralKit Example System".
|
||||
2. **Avatar**: This is the image that's used for proxying messages from this member.
|
||||
3. **Display name**: This is shown in proxy messages on all servers in place of their name if it is set.
|
||||
4. **Server nickname**: This is like display name, but set for specific servers (in this case the PluralKit support server).
|
||||
5. **Birthdate**: This is the member's set birthday, it can be with or without the year.
|
||||
6. **Pronouns**: This is the member's pronouns. It's a free text entry field, so you can put anything you'd like.
|
||||
7. **Message count**: This is the total number of messages this member has ever sent through proxies.
|
||||
8. **Proxy tags**: This is a list of the member's proxy tags. We will go more in depth into them in a bit!
|
||||
9. **Colour**: This is the member's colour, it affects the sidebar of the card on the left. **It does not affect the proxy colour, due to a Discord limitation.**
|
||||
10. **Description**: This is the member description. Similar to the system description, you can put anything you'd like here.
|
||||
11. **System ID**: This is the ID of the system this member is part of. In this case it's the ID for the PluralKit Example System we saw above.
|
||||
12. **Member ID**: This is the auto-generated ID for the member. You can always use this ID to refer to a specific member, even if the name contains hard-to-type characters.
|
||||
13. **Created on**: This is the date and time the member was created.
|
||||
|
||||
### Creating a member
|
||||
This is just as easy as creating a system, but there are a few more things you will want to do immediately after. First you run `pk;member new <name>`, so if you want to create a member named Myriad, you would run `pk;member new Myriad`.
|
||||
Next, for proxying later, you will want to set an avatar for your new member! This is done simply by using `pk;member <member> avatar <link to avatar>`. For example,
|
||||
```
|
||||
pk;member Myriad avatar http://pluralkit.me/assets/myriad.png
|
||||
```
|
||||
|
||||
You can also leave out the image link, and instead attach an image with the command. That'll work too!
|
||||
|
||||
For more info on what you can do with members, check out [the member management section of the user guide](/guide#member-management).
|
||||
|
||||
----
|
||||
|
||||
## Proxies
|
||||
Proxies are probably the most important part of PluralKit, they are literally what the bot was made for. Below is an example of a proxied message:
|
||||
|
||||

|
||||
|
||||
### Parts to a proxy message
|
||||
1. **The name**: This is the member's name, display name, or server nickname, depending on what's set (server nickname overrides display name, which overrides the normal name). In this case, it's **Myriad "Big Boss" Kit**.
|
||||
2. **The system tag**: If a system tag is set, this will will appear right after the name. In this case, it's **\| PluralKit 🦊**.
|
||||
3. **The BOT badge**: All proxies have this due to how the proxy service works. It's not possible to remove.
|
||||
3. **The message**: The message you proxied through the bot - this is what was on the "inside" of the proxy tags, which we will explain below.
|
||||
|
||||
### Parts to a proxy tag
|
||||
A proxy tag is what tells PluralKit how to know to proxy a member. It looks like this:
|
||||
```
|
||||
pretextpost
|
||||
```
|
||||
and has 3 parts.
|
||||
1. **Prefix**: In this case, `pre`. This tells PluralKit what to look for at the **start** of the message
|
||||
2. **Separator**: This is always the word `text`, all-lowercase. It tells PluralKit where the prefix ends and the suffix starts.
|
||||
3. **Suffix**: In this case, `post`. This tells PluralKit to what to look for at the **end** of a message
|
||||
|
||||
You can imagine that this is an "example proxy", where the intended message is the word `text`.
|
||||
|
||||
In this example, typing a message such as
|
||||
```
|
||||
pre This is an example message post
|
||||
```
|
||||
would result in the message "This is an example message" being proxied.
|
||||
|
||||
### Setting a proxy tag
|
||||
To set a proxy tag you need to know 3 things. The member you wish to set the tags for, the prefix for the tag, and the suffix for the tag.
|
||||
Once you know these things you can run the command:
|
||||
```
|
||||
pk;member [member] proxy [prefix]text[suffix]
|
||||
```
|
||||
For example, if you want messages starting with `{` and ending with `}` to be proxied by Myriad, you could run
|
||||
```
|
||||
pk;member Myriad proxy {text}
|
||||
```
|
||||
Now when you type a message such as `{this is an example message}` it will be proxied by Myriad.
|
||||
|
||||
You do not need both to set it. If you do not set a prefix or a suffix, it will not care what is at the start or end of the message respectively. For more examples [click here](#more-proxy-examples)
|
||||
|
||||
For a more detailed guide on proxying, have a look at the [proxying section of the user guide](/guide#proxying).
|
||||
|
||||
### Reactions
|
||||
When you come across a proxied message, or you have proxied a message, there are a few handy reactions you can add to the message for some more functionality!
|
||||
|
||||
❌ (red X): This reaction will cause the message to be deleted, but only if you are using the account that sent the message.
|
||||
|
||||
❓ (question mark): This reaction will DM you a message containing details on who sent the message, the member that it proxied, and the system it was from. When you react with this, you will receive a DM that looks like this:
|
||||
|
||||

|
||||
|
||||
❗ (exclamation mark): This reaction will send a message to the channel the proxied message was sent in, pinging both you and the sender of the message. That message will look like this:
|
||||
|
||||

|
||||
|
||||
### More proxy examples
|
||||
How to read these examples: The smaller code block with "Example Message" in it is the message you would like to proxy, the larger code block immediately after it is the command you would need to set the member Myriad to respond to that proxy
|
||||
|
||||
`Example message - Myriad`
|
||||
```
|
||||
pk;member Myriad proxy text- Myriad
|
||||
```
|
||||
|
||||
`M. Example message`
|
||||
```
|
||||
pk;member Myriad proxy M.text
|
||||
```
|
||||
|
||||
`🎩Example message`
|
||||
```
|
||||
pk;member Myriad proxy 🎩text
|
||||
```
|
||||
*Note: Custom emojis do work, but look a bit weird in the text form*
|
||||
|
||||
`-- Example message --`
|
||||
```
|
||||
pk;member Myriad proxy -- text --
|
||||
```
|
||||
*Note: Having a space between the prefix/suffix and `text` will mean that the space is required. In this example `--Example message--` will not proxy.*
|
27
docs/content/index.md
Normal file
@@ -0,0 +1,27 @@
|
||||
---
|
||||
# home: true
|
||||
# heroImage: https://v1.vuepress.vuejs.org/hero.png
|
||||
# tagline: Documentation for PluralKit
|
||||
# actionText: Quick Start →
|
||||
# actionLink: /guide/
|
||||
# features:
|
||||
# - title: Feature 1 Title
|
||||
# details: Feature 1 Description
|
||||
# - title: Feature 2 Title
|
||||
# details: Feature 2 Description
|
||||
# - title: Feature 3 Title
|
||||
# details: Feature 3 Description
|
||||
# footer: Made by with ❤️
|
||||
title: Home
|
||||
---
|
||||
|
||||
# PluralKit
|
||||
|
||||
PluralKit is a bot designed for plural communities on Discord. It allows you to register systems, maintain system information, set up message proxying, log switches, and more.
|
||||
|
||||
This bot detects messages with certain tags associated with a profile, then replaces that message under a "pseudo-account" of that profile using webhooks. This is useful for multiple people sharing one body (aka "systems"), people who wish to roleplay as different characters without having several accounts, or anyone else who may want to post messages as a different person from the same account.
|
||||
|
||||
#### for example...
|
||||

|
||||
|
||||
For more information, see the links to the left, or click [here](https://discord.com/oauth2/authorize?client_id=466378653216014359&scope=bot&permissions=536995904) to invite the bot to your server!
|
32
docs/content/privacy-policy.md
Normal file
@@ -0,0 +1,32 @@
|
||||
---
|
||||
title: Privacy Policy
|
||||
description: I'm not a lawyer. I don't want to write a 50 page document no one wants to (or can) read. It's short, I promise.
|
||||
permalink: /privacy
|
||||
---
|
||||
|
||||
# Privacy Policy
|
||||
|
||||
I'm not a lawyer. I don't want to write a 50 page document no one wants to (or can) read. In short:
|
||||
|
||||
This is the data PluralKit collects indefinitely:
|
||||
* Information *you give the bot* (eg. system/member profiles, switch history, linked accounts, etc)
|
||||
* Metadata about proxied messages (sender account ID, sender system/member, timestamp)
|
||||
* Aggregate anonymous usage metrics (eg. gateway events received/second, messages proxied/second, commands executed/second)
|
||||
* This is visible on [https://stats.pluralkit.me/](https://stats.pluralkit.me/)
|
||||
* Nightly database backups of the above information
|
||||
* High-level logs of actions taken on the bot (eg. systems created or deleted, switches logged, etc)
|
||||
|
||||
This is the data PluralKit does *not* collect:
|
||||
* Anything not listed above, including...
|
||||
* Proxied message *contents* (they are fetched on-demand from the original message object when queried)
|
||||
* Metadata about deleted messages, members, switches or systems
|
||||
* Information added *and deleted* between nightly backups
|
||||
* Information about messages that *aren't* proxied through PluralKit
|
||||
|
||||
System and member information (names, member lists, descriptions, etc) are public by default, and can be looked up by anyone given a system/member ID or an account ID. This can be changed using the [privacy settings](/guide#privacy).
|
||||
|
||||
You can export your system information using the `pk;export` command. This does not include message metadata (as the file would be huge). If there's demand for a command to export that, [let me know on GitHub](https://github.com/xSke/PluralKit/issues).
|
||||
|
||||
You can delete your information using `pk;system delete`. This will delete all system information and associated members, switches, and messages. This will not delete your information from the database backups. Contact me if you want that wiped, too.
|
||||
|
||||
The bot is [open-source](https://github.com/xSke/PluralKit). While I can't *prove* this is the code that's running on the production server... it is, promise.
|
36
docs/content/tips-and-tricks.md
Normal file
@@ -0,0 +1,36 @@
|
||||
---
|
||||
layout: default
|
||||
permalink: /tips
|
||||
title: Tips and Tricks
|
||||
---
|
||||
|
||||
# Tips and Tricks
|
||||
|
||||
## Use command shorthands
|
||||
PluralKit has a couple of useful command shorthands to reduce the typing:
|
||||
|
||||
|Original|Shorthand|
|
||||
|---|---|
|
||||
|pk;system|pk;s|
|
||||
|pk;system list|pk;s l|
|
||||
|pk;system list full|pk;s l f|
|
||||
|pk;system fronter|pk;s f|
|
||||
|pk;system fronthistory|pk;s fh|
|
||||
|pk;system frontpercent|pk;s fp|
|
||||
|pk;member|pk;m|
|
||||
|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).
|
553
docs/content/user-guide.md
Normal file
@@ -0,0 +1,553 @@
|
||||
---
|
||||
title: User Guide
|
||||
description: PluralKit's user guide contains a walkthrough of the bot's features, as well as how to use them.
|
||||
permalink: /guide
|
||||
|
||||
# To prevent sidebar from getting super long
|
||||
sidebarDepth: 1
|
||||
---
|
||||
|
||||
# User Guide
|
||||
|
||||
## Adding the bot to your server
|
||||
If you want to use PluralKit on a Discord server, you must first *add* it to the server in question. For this, you'll need the *Manage Server* permission on there.
|
||||
|
||||
Use this link to add the bot to your server:
|
||||
|
||||
[https://discord.com/oauth2/authorize?client_id=466378653216014359&scope=bot&permissions=536995904](https://discord.com/oauth2/authorize?client_id=466378653216014359&scope=bot&permissions=536995904)
|
||||
|
||||
Once you go through the wizard, the bot account will automatically join the server you've chosen. Please ensure the bot has the *Read Messages*, *Send Messages*, *Manage Messages*, *Attach Files* and *Manage Webhooks* permission in the channels you want it to work in.
|
||||
|
||||
## System management
|
||||
In order to do most things with the PluralKit bot, you'll need to have a system registered with it. A *system* is a collection of *system members* that may be used by one or more *Discord accounts*.
|
||||
|
||||
### Creating a system
|
||||
If you do not already have a system registered, use the following command to create one:
|
||||
|
||||
pk;system new
|
||||
|
||||
Optionally, you can attach a *system name*, which will be displayed in various information cards, like so:
|
||||
|
||||
pk;system new My System Name
|
||||
|
||||
### Viewing information about a system
|
||||
To view information about your own system, simply type:
|
||||
|
||||
pk;system
|
||||
|
||||
To view information about *a different* system, there are a number of ways to do so. You can either look up a system by @mention, by account ID, or by system ID. For example:
|
||||
|
||||
pk;system @Craig#5432
|
||||
pk;system 466378653216014359
|
||||
pk;system abcde
|
||||
|
||||
### System description
|
||||
If you'd like to add a small blurb to your system information card, you can add a *system description*. To do so, use the `pk;system description` command, as follows:
|
||||
|
||||
pk;system description This is my system description. Hello. Lorem ipsum dolor sit amet.
|
||||
|
||||
There's a 1000 character length limit on your system description - which is quite a lot!
|
||||
|
||||
If you'd like to remove your system description, just type `pk;system description` without any further parameters.
|
||||
|
||||
### System avatars
|
||||
If you'd like your system to have an associated "system avatar", displayed on your system information card, you can add a system avatar. To do so, use the `pk;system avatar` command. You can either supply it with an direct URL to an image, or attach an image directly. For example.
|
||||
|
||||
pk;system avatar http://placebeard.it/512.jpg
|
||||
pk;system avatar [with attached image]
|
||||
|
||||
To clear your avatar, simply type `pk;system avatar` with no attachment or link.
|
||||
|
||||
### System tags
|
||||
Your system tag is a little snippet of text that'll be added to the end of all proxied messages.
|
||||
For example, if you want to proxy a member named `James`, and your system tag is `| The Boys`, the final name displayed
|
||||
will be `James | The Boys`. This is useful for identifying your system in-chat, and some servers may require you use
|
||||
a system tag. Note that emojis *are* supported! To set one, use the `pk;system tag` command, like so:
|
||||
|
||||
pk;system tag | The Boys
|
||||
pk;system tag (Test System)
|
||||
pk;system tag 🛰️
|
||||
|
||||
If you want to remove your system tag, just type `pk;system tag` with no extra parameters.
|
||||
|
||||
**NB:** When proxying, the *total webhook username* must be 32 characters or below. As such, if you have a long system name, your tag might be enough
|
||||
to bump it over that limit. PluralKit will warn you if you have a member name/tag combination that will bring the combined username above the limit.
|
||||
You can either make the member name or the system tag shorter to solve this.
|
||||
|
||||
### Adding or removing Discord accounts to the system
|
||||
If you have multiple Discord accounts you want to use the same system on, you don't need to create multiple systems.
|
||||
Instead, you can *link* the same system to multiple accounts.
|
||||
|
||||
Let's assume the account you want to link to is called @Craig#5432. You'd link it to your *current* system by running this command from an account that already has access to the system:
|
||||
|
||||
pk;link @Craig#5432
|
||||
|
||||
PluralKit will require you to confirm the link by clicking on a reaction *from the other account*.
|
||||
|
||||
If you now want to unlink that account, use the following command:
|
||||
|
||||
pk;unlink @Craig#5432
|
||||
|
||||
You may not remove the only account linked to a system, as that would leave the system inaccessible. Both the `pk;link` and `pk;unlink` commands work with account IDs instead of @mentions, too.
|
||||
|
||||
### Setting a system time zone
|
||||
PluralKit defaults to showing dates and times in [UTC](https://en.wikipedia.org/wiki/Coordinated_Universal_Time).
|
||||
If you'd like, you can set a *system time zone*, and as such every date and time displayed in PluralKit
|
||||
(on behalf of your system) will be in the system time zone. To do so, use the `pk;system timezone` command, like so:
|
||||
|
||||
pk;system timezone Europe/Copenhagen
|
||||
pk;system timezone America/New_York
|
||||
pk;system timezone DE
|
||||
pk;system timezone 🇬🇧
|
||||
|
||||
You can specify time zones in various ways. In regions with large amounts of time zones (eg. the Americas, Europe, etc),
|
||||
specifying an exact time zone code is the best way. To get your local time zone code, visit [this site](https://xske.github.io/tz).
|
||||
You can see the full list [here, on Wikipedia](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) (see the column *TZ database name*).
|
||||
You can also search by country code, either by giving the two-character [*ISO-3166-1 alpha-2* country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) (eg. `GB` or `DE`), or just by a country flag emoji.
|
||||
|
||||
To clear a time zone, type `pk;system timezone` without any parameters.
|
||||
|
||||
### Deleting a system
|
||||
If you want to delete your own system, simply use the command:
|
||||
|
||||
pk;system delete
|
||||
|
||||
You will need to verify by typing the system's ID when the bot prompts you to - to prevent accidental deletions.
|
||||
|
||||
## Member management
|
||||
|
||||
In order to do most things related to PluralKit, you need to work with *system members*.
|
||||
|
||||
Most member commands follow the format of `pk;member MemberName verb Parameter`. Note that if a member's name has multiple words, you'll need to enclose it in "double quotes" throughout the commands below.
|
||||
|
||||
### Creating a member
|
||||
You can't do much with PluralKit without having registered members with your system, but doing so is quite simple - just use the `pk;member new` command followed by the member's name, like so:
|
||||
|
||||
pk;member new John
|
||||
pk;member new Craig Smith
|
||||
|
||||
As the one exception to the rule above, if the name consists of multiple words you must *not* enclose it in double quotes.
|
||||
|
||||
### Looking up member info
|
||||
To view information about a member, there are a couple ways to do it. Either you can address a member by their name (if they're in your own system), or by their 5-character *member ID*, like so:
|
||||
|
||||
pk;member John
|
||||
pk;member qazws
|
||||
|
||||
Member IDs are the only way to address a member in another system, and you can find it in various places - for example the system's member list, or on a message info card gotten by reacting to messages with a question mark.
|
||||
|
||||
### Listing system members
|
||||
To list all the members in a system, use the `pk;system list` command. This will show a paginated list of all member names in the system. You can either run it on your own system, or another - like so:
|
||||
|
||||
pk;system list
|
||||
pk;system @Craig#5432 list
|
||||
pk;system qazws list
|
||||
|
||||
If you want a more detailed list, with fields such as pronouns and description, add the word `full` to the end of the command, like so:
|
||||
|
||||
pk;system list full
|
||||
pk;system @Craig#5432 list full
|
||||
pk;system qazws list full
|
||||
|
||||
### Member renaming
|
||||
If you want to change the name of a member, you can use the `pk;member rename` command, like so:
|
||||
|
||||
pk;member John rename Joanne
|
||||
pk;member "Craig Smith" rename "Craig Johnson"
|
||||
|
||||
### Member display names
|
||||
Normally, when proxying a member, the name displayed in the proxied message will be the member's name. However, in some cases
|
||||
you may want to display a different name. For example, you may want to include a member's pronouns inside the proxied name,
|
||||
indicate a subsystem, include emojis or symbols that don't play nice with the command syntax, or just in general show a different name from the member's "canonical" name.
|
||||
|
||||
In such cases you can set the member's *display name*. Which will, well, display that name instead. You can set
|
||||
a display name using the `pk;member displayname` command, like so:
|
||||
|
||||
pk;member John displayname Jonathan
|
||||
pk;member Robert displayname Bob (he/him)
|
||||
|
||||
To remove a display name, just use the same command with no last parameter, eg:
|
||||
|
||||
pk;member John displayname
|
||||
|
||||
This will remove the display name, and thus the member will be proxied with their canonical name.
|
||||
|
||||
### Member server display names
|
||||
If you'd like to set a display name (as above), but only for a specific server, you can set the member's *server display name*.
|
||||
This functions just like global display names, but only in the same server you set them in. For example:
|
||||
|
||||
pk;member John servername AdminJohn
|
||||
|
||||
The server name applies to the same server you run the command in, so naturally this command doesn't function in DMs (as you cannot proxy in DMs).
|
||||
|
||||
### Member description
|
||||
In the same way as a system can have a description, so can a member. You can set a description using the `pk;member description` command, like so:
|
||||
|
||||
pk;member John description John is a very cool person, and you should give him hugs.
|
||||
|
||||
As with system descriptions, the member description has a 1000 character length limit.
|
||||
To clear a member description, use the command with no additional parameters (eg. `pk;member John description`).
|
||||
|
||||
### Member color
|
||||
A system member can have an associated color value.
|
||||
This color is *not* displayed as a name color on proxied messages due to a Discord limitation,
|
||||
but it's shown in member cards, and it can be used in third-party apps, too.
|
||||
To set a member color, use the `pk;member color` command with [a hexadecimal color code](https://htmlcolorcodes.com/), like so:
|
||||
|
||||
pk;member John color #ff0000
|
||||
pk;member John color #87ceeb
|
||||
|
||||
To clear a member color, use the command with no color code argument (eg. `pk;member John color`).
|
||||
|
||||
### Member avatar
|
||||
If you want your member to have an associated avatar to display on the member information card and on proxied messages, you can set the member avatar. To do so, use the `pk;member avatar` command. You can either supply it with an direct URL to an image, or attach an image directly. For example.
|
||||
|
||||
pk;member John avatar http://placebeard.it/512.jpg
|
||||
pk;member "Craig Johnson" avatar (with an attached image)
|
||||
|
||||
To preview the current avatar (if one is set), use the command with no arguments:
|
||||
|
||||
pk;member John avatar
|
||||
|
||||
To clear your avatar, use the subcommand `avatar clear` (eg. `pk;member John avatar clear`).
|
||||
|
||||
### Member server avatar
|
||||
You can also set an avatar for a specific server. This will "override" the normal avatar, and will be used when proxying messages and looking up member cards in that server. To do so, use the `pk;member serveravatar` command, in the same way as the normal avatar command above:
|
||||
|
||||
pk;member John serveravatar
|
||||
pk;member John serveravatar http://placebeard.it/512.jpg
|
||||
pk;member "Craig Johnson" serveravatar (with an attached image)
|
||||
pk;member John serveravatar clear
|
||||
|
||||
### Member pronouns
|
||||
If you want to list a member's preferred pronouns, you can use the pronouns field on a member profile. This is a free text field, so you can put whatever you'd like in there (with a 100 character limit), like so:
|
||||
|
||||
pk;member John pronouns he/him
|
||||
pk;member "Craig Johnson" pronouns anything goes, really
|
||||
pk;member Skyler pronouns xe/xir or they/them
|
||||
|
||||
To remove a member's pronouns, use the command with no pronoun argument (eg. `pk;member John pronouns`).
|
||||
|
||||
### Member birthdate
|
||||
If you want to list a member's birthdate on their information card, you can set their birthdate through PluralKit using the `pk;member birthdate` command. Please use [ISO-8601 format](https://xkcd.com/1179/) (`YYYY-MM-DD`) for best results, like so:
|
||||
|
||||
pk;member John birthdate 1996-07-24
|
||||
pk;member "Craig Johnson" birthdate 2004-02-28
|
||||
|
||||
You can also set a birthdate without a year, either in `MM-DD` format or `Month Day` format, like so:
|
||||
|
||||
pk;member John birthdate 07-24
|
||||
pk;member "Craig Johnson" birthdate Feb 28
|
||||
|
||||
To clear a birthdate, use the command with no birthday argument (eg. `pk;member John birthdate`).
|
||||
|
||||
### Deleting members
|
||||
If you want to delete a member, use the `pk;member delete` command, like so:
|
||||
|
||||
pk;member John delete
|
||||
|
||||
You'll need to confirm the deletion by replying with the member's ID when the bot asks you to - this is to avoid accidental deletion.
|
||||
|
||||
## Proxying
|
||||
Proxying is probably the most important part of PluralKit. This allows you to essentially speak "as" the member,
|
||||
with the proper name and avatar displayed on the message. To do so, you must at least [have created a member](#creating-a-system).
|
||||
|
||||
### Setting up proxy tags
|
||||
You'll need to register a set of *proxy tags*, which are prefixes and/or suffixes you "enclose" the real message in, as a signal to PluralKit to indicate
|
||||
which member to proxy as. Common proxy tags include `[square brackets]`, `{curly braces}` or `A:letter prefixes`.
|
||||
|
||||
To set a proxy tag, use the `pk;member proxy` command on the member in question. You'll need to provide a "proxy example", containing the word `text`.
|
||||
For example, if you want square brackets, the proxy example must be `[text]`. If you want a letter prefix, make it something like `A:text`. For example:
|
||||
|
||||
pk;member John proxy [text]
|
||||
pk;member "Craig Johnson" proxy {text}
|
||||
pk;member John proxy J:text
|
||||
|
||||
You can have any proxy tags you want, including one containing emojis.
|
||||
|
||||
You can now type a message enclosed in your proxy tags, and it'll be deleted by PluralKit and reposted with the appropriate member name and avatar (if set).
|
||||
|
||||
**NB:** If you want `<angle brackets>` as proxy tags, there is currently a bug where custom server emojis will (wrongly)
|
||||
be interpreted as proxying with that member (see [issue #37](https://github.com/xSke/PluralKit/issues/37)). The current workaround is to use different proxy tags.
|
||||
|
||||
### Using multiple distinct proxy tag pairs
|
||||
If you'd like to proxy a member in multiple ways (for example, a name or a nickname, uppercase and lowercase variants, etc), you can add multiple tag pairs.
|
||||
When proxying, you may then use any of the tags to proxy for that specific member.
|
||||
|
||||
To add a proxy tag to a member, use the `pk;member proxy add` command:
|
||||
pk;member John proxy add {text}
|
||||
pk;member Craig proxy add C:text
|
||||
|
||||
To remove a proxy tag from a member, use the `pk;member proxy remove` command:
|
||||
pk;member John proxy remove {text}
|
||||
pk;member Craig proxy remove C:text
|
||||
|
||||
### Keeping your proxy tags
|
||||
If you'd like your proxied messages to include the proxy tags, you can enable the "keep proxy tags" option for a given member, like so:
|
||||
|
||||
pk;member John keepproxy on
|
||||
|
||||
Turning the option off is similar - replace "on" with "off" in the command. The default value for every member is off. When proxying
|
||||
a member with multiple proxy tags, the proxy tag used to trigger a given proxy will be included.
|
||||
|
||||
The practical effect of this is:
|
||||
* **Keep proxy tags on:** `[Message goes here]` -> [Message goes here]
|
||||
* **Keep proxy tags off:** `[Message goes here]` -> Message goes here
|
||||
|
||||
### Querying message information
|
||||
If you want information about a proxied message (eg. for moderation reasons), you can query the message for its sender account, system, member, etc.
|
||||
|
||||
Either you can react to the message itself with the ❔ or ❓ emoji, which will DM you information about the message in question,
|
||||
or you can use the `pk;message` command followed by [the message's ID](https://support.discord.com/hc/en-us/articles/206346498-Where-can-I-find-my-User-Server-Message-ID-).
|
||||
|
||||
### Pinging a specific user
|
||||
If you'd like to "ping" the account behind a proxied message without having to query the message and ping them yourself,
|
||||
you can react to the message with the 🔔 or ❗ emoji, and PluralKit will ping the relevant member and account in the same
|
||||
channel on your behalf with a link to the message you reacted to.
|
||||
|
||||
### Disabling proxying on a per-server basis
|
||||
If you need to disable proxying messages for your system entirely in a specific server (for example, if you'd like to
|
||||
use a different proxy bot there), you can type `pk;system proxy on/off` to do that.
|
||||
|
||||
### Deleting messages
|
||||
Since the messages will be posted by PluralKit's webhook, there's no way to delete the message as you would a normal user message.
|
||||
To delete a PluralKit-proxied message, you can react to it with the ❌ emoji. Note that this only works if the message has
|
||||
been sent from your own account.
|
||||
|
||||
### Autoproxying
|
||||
The bot's *autoproxy* feature allows you to have messages be proxied without directly including the proxy tags. Autoproxy can be set up in various ways. There are three autoproxy modes currently implemented:
|
||||
|
||||
To see your system's current autoproxy settings, simply use the command:
|
||||
pk;autoproxy
|
||||
|
||||
To disable autoproxying for the current server, use the command:
|
||||
pk;autoproxy off
|
||||
|
||||
*(hint: `pk;autoproxy` can be shortened to `pk;ap` in all related commands)*
|
||||
|
||||
#### Front mode
|
||||
This autoproxy mode will proxy messages as the current *first* fronter of the system. If you register a switch with `Alice` and `Bob`, messages without proxy tags will be autoproxied as `Alice`.
|
||||
To enable front-mode autoproxying for a given server, use the following command:
|
||||
|
||||
pk;autoproxy front
|
||||
|
||||
#### Latch mode
|
||||
This autoproxy mode will essentially "continue" previous proxy tags. If you proxy a message with `Alice`'s proxy tags, messages posted afterwards will be proxied as Alice. Proxying again with someone else's proxy tags, say, `Bob`, will cause messages *from then on* to be proxied as Bob.
|
||||
In other words, it means proxy tags become "sticky". This will carry over across all channels in the same server.
|
||||
|
||||
To enable latch-mode autoproxying for a given server, use the following command:
|
||||
|
||||
pk;autoproxy latch
|
||||
|
||||
#### Member mode
|
||||
This autoproxy mode will autoproxy for a specific selected member, irrelevant of past proxies or fronters.
|
||||
|
||||
To enable member-mode autoproxying for a given server, use the following command, where `<member>` is a member name (in "quotes" if multiple words) or 5-letter ID:
|
||||
|
||||
pk;autoproxy <member>
|
||||
|
||||
## Managing switches
|
||||
PluralKit allows you to log member switches through the bot.
|
||||
Essentially, this means you can mark one or more members as *the current fronter(s)* for the duration until the next switch.
|
||||
You can then view the list of switches and fronters over time, and get statistics over which members have fronted for how long.
|
||||
|
||||
### Logging switches
|
||||
To log a switch, use the `pk;switch` command with one or more members. For example:
|
||||
|
||||
pk;switch John
|
||||
pk;switch "Craig Johnson" John
|
||||
|
||||
Note that the order of members are preserved (this is useful for indicating who's "more" at front, if applicable).
|
||||
If you want to specify a member with multiple words in their name, remember to encase the name in "double quotes".
|
||||
|
||||
### Switching out
|
||||
If you want to log a switch with *no* members, you can log a switch-out as follows:
|
||||
|
||||
pk;switch out
|
||||
|
||||
### Moving switches
|
||||
If you want to log a switch that happened further back in time, you can log a switch and then *move* it back in time, using the `pk;switch move` command.
|
||||
You can either specify a time either in relative terms (X days/hours/minutes/seconds ago) or in absolute terms (this date, at this time).
|
||||
Absolute times will be interpreted in the [system time zone](#setting-a-system-time-zone). For example:
|
||||
|
||||
pk;switch move 1h
|
||||
pk;switch move 4d12h
|
||||
pk;switch move 2 PM
|
||||
pk;switch move May 8th 4:30 PM
|
||||
|
||||
Note that you can't move a switch *before* the *previous switch*, to avoid breaking consistency. Here's a rough ASCII-art illustration of this:
|
||||
|
||||
YOU CAN NOT YOU CAN
|
||||
MOVE HERE MOVE HERE CURRENT SWITCH
|
||||
v v START NOW
|
||||
[===========================] | v v
|
||||
[=== PREVIOUS SWITCH ===]| |
|
||||
\________________________[=== CURRENT SWITCH ===]
|
||||
|
||||
----- TIME AXIS ---->
|
||||
|
||||
### Delete switches
|
||||
If you'd like to delete the most recent switch, use the `pk;switch delete` command. You'll need to confirm
|
||||
the deletion by clicking a reaction.
|
||||
|
||||
If you'd like to clear your system's entire switch history, use the `pk;switch delete all` command. This isn't reversible!
|
||||
|
||||
### Querying fronter
|
||||
To see the current fronter in a system, use the `pk;system fronter` command. You can use this on your current system, or on other systems. For example:
|
||||
|
||||
pk;system fronter
|
||||
pk;system @Craig#5432 fronter
|
||||
pk;system qazws fronter
|
||||
|
||||
### Querying front history
|
||||
To look at the front history of a system (currently limited to the last 10 switches). use the `pk;system fronthistory` command, for example:
|
||||
|
||||
pk;system fronthistory
|
||||
pk;system @Craig#5432 fronthistory
|
||||
pk;system qazws fronthistory
|
||||
|
||||
### Querying front percentage
|
||||
To look at the per-member breakdown of the front over a given time period, use the `pk;system frontpercent` command. If you don't provide a time period, it'll default to 30 days. For example:
|
||||
|
||||
pk;system frontpercent
|
||||
pk;system @Craig#5432 frontpercent 7d
|
||||
pk;system qazws frontpercent 100d12h
|
||||
|
||||
Note that in cases of switches with multiple members, each involved member will have the full length of the switch counted towards it. This means that the percentages may add up to over 100%.
|
||||
|
||||
## Privacy
|
||||
There are various reasons you may not want information about your system or your members to be public. As such, there are a few controls to manage which information is publicly accessible or not.
|
||||
|
||||
### System privacy
|
||||
At the moment, there are four aspects of system privacy that can be configured.
|
||||
|
||||
- System description
|
||||
- Current fronter
|
||||
- Front history
|
||||
- Member list
|
||||
|
||||
Each of these can be set to **public** or **private**. When set to **public**, anyone who queries your system (by account or system ID, or through the API), will see this information. When set to **private**, the information will only be shown when *you yourself* query the information. The cards will still be displayed in the channel the commands are run in, so it's still your responsibility not to pull up information in servers where you don't want it displayed.
|
||||
|
||||
To update your system privacy settings, use the following commands:
|
||||
|
||||
pk;system privacy <subject> <level>
|
||||
|
||||
where `<subject>` is either `description`, `fronter`, `fronthistory` or `list`, corresponding to the options above, and `<level>` is either `public` or `private`. `<subject>` can also be `all` in order to change all subjects at once.
|
||||
|
||||
For example:
|
||||
|
||||
pk;system privacy description private
|
||||
pk;system privacy fronthistory public
|
||||
pk;system privacy list private
|
||||
|
||||
When the **member list** is **private**, other users will not be able to view the full member list of your system, but they can still query individual members given their 5-letter ID. If **current fronter** is private, but **front history** isn't, someone can still see the current fronter by looking at the history (this combination doesn't make much sense).
|
||||
|
||||
### Member privacy
|
||||
There are also seven options for configuring member privacy;
|
||||
|
||||
- Name
|
||||
- Description
|
||||
- Avatar
|
||||
- Birthday
|
||||
- Pronouns
|
||||
- Metadata *(message count, creation date, etc)*
|
||||
- Visibility *(whether the member shows up in member lists)*
|
||||
|
||||
As with system privacy, each can be set to **public** or **private**. The same rules apply for how they are shown, too. When set to **public**, anyone who queries your system (by account or system ID, or through the API), will see this information. When set to **private**, the information will only be shown when *you yourself* query the information. The cards will still be displayed in the channel the commands are run in, so it's still your responsibility not to pull up information in servers where you don't want it displayed.
|
||||
|
||||
However, there are two catches:
|
||||
- When the **name** is set to private, it will be replaced by the member's **display name**, but only if they have one! If the member has no display name, **name privacy will not do anything**. PluralKit still needs some way to refer to a member by name :)
|
||||
- When **visibility** is set to private, the member will not show up in member lists unless `-all` is used in the command (and you are part of the system).
|
||||
|
||||
To update a members privacy you can use the command:
|
||||
|
||||
member <member> privacy <subject> <level>
|
||||
|
||||
where `<member>` is the name or the id of a member in your system, `<subject>` is either `name`, `description`, `avatar`, `birthday`, `pronouns`, `metadata`, or `visiblity` corresponding to the options above, and `<level>` is either `public` or `private`. `<subject>` can also be `all` in order to change all subjects at once.
|
||||
`metadata` will affect the message count, the date created, the last fronted, and the last message information.
|
||||
|
||||
For example:
|
||||
|
||||
pk;member John privacy visibility private
|
||||
pk;member "Craig Johnson" privacy description public
|
||||
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.
|
||||
|
||||
### Importing from Tupperbox
|
||||
If you're a user of the *other proxying bot* Tupperbox, you can import system and member information from there. This is a fairly simple process:
|
||||
|
||||
1. Export your data from Tupperbox:
|
||||
```
|
||||
tul!export
|
||||
```
|
||||
2. Copy the URL for the data file (or download it)
|
||||
3. Import your data into PluralKit:
|
||||
```
|
||||
pk;import https://link/to/the/data/file.json
|
||||
```
|
||||
*(alternatively, run `pk;import` by itself and attach the .json file)*
|
||||
|
||||
Note that while Tupperbox supports features such as multiple proxies per member, per-member system tags, and member groups, PluralKit does not.
|
||||
PluralKit will warn you when you're importing a Tupperbox file that makes use of such features, as they will not carry over.
|
||||
|
||||
### Importing from PluralKit
|
||||
If you have an exported file from PluralKit, you can import system, member and switch information from there like so:
|
||||
1. Export your data from PluralKit:
|
||||
```
|
||||
pk;export
|
||||
```
|
||||
2. Copy the URL for the data file (or download it)
|
||||
3. Import your data into PluralKit:
|
||||
```
|
||||
pk;import https://link/to/the/data/file.json
|
||||
```
|
||||
*(alternatively, run `pk;import` by itself and attach the .json file)*
|
||||
|
||||
### Exporting your PluralKit data
|
||||
To export all the data associated with your system, run the `pk;export` command. This will send you a JSON file containing your system, member, and switch information.
|