From bc9477465d668a54670db0bfd2dbc3a49bc2e8ac Mon Sep 17 00:00:00 2001 From: TheCatLady <52870424+TheCatLady@users.noreply.github.com> Date: Sun, 21 Mar 2021 20:15:20 -0400 Subject: [PATCH] docs: add email & Discord notification info (#1251) * docs: add email & Discord notification info * docs: update TOC --- docs/SUMMARY.md | 4 +- docs/using-overseerr/notifications/README.md | 14 ++--- docs/using-overseerr/notifications/discord.md | 21 ++++++++ docs/using-overseerr/notifications/email.md | 54 +++++++++++++++++++ .../using-overseerr/notifications/webhooks.md | 12 +++-- 5 files changed, 90 insertions(+), 15 deletions(-) create mode 100644 docs/using-overseerr/notifications/discord.md create mode 100644 docs/using-overseerr/notifications/email.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index fdc2c4cb5..0e84bdeb7 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -10,7 +10,9 @@ - [Settings](using-overseerr/settings/README.md) - [Notifications](using-overseerr/notifications/README.md) - - [Custom Webhooks](using-overseerr/notifications/webhooks.md) + - [Email](using-overseerr/notifications/email.md) + - [Discord](using-overseerr/notifications/discord.md) + - [Webhooks](using-overseerr/notifications/webhooks.md) ## Support diff --git a/docs/using-overseerr/notifications/README.md b/docs/using-overseerr/notifications/README.md index 3f13c0a90..05005233f 100644 --- a/docs/using-overseerr/notifications/README.md +++ b/docs/using-overseerr/notifications/README.md @@ -2,10 +2,10 @@ Overseerr already supports a good number of notification agents, such as **Discord**, **Slack** and **Pushover**. New agents are always considered for development, if there is enough demand for it. -## Currently Supported Notification Agents +## Supported Notification Agents -- Discord -- Email +- [Email](./email.md) +- [Discord](./discord.md) - Pushbullet - Pushover - Slack @@ -14,15 +14,11 @@ Overseerr already supports a good number of notification agents, such as **Disco ## Setting Up Notifications -Configuring your notifications is _very simple_. First, you will need to visit the **Settings** page and click **Notifications** in the menu. This will present you with all of the currently available notification agents. Click on each one individually to configure them. +Configuring your notifications is quite simple. First, you will need to visit the **Settings** page and click **Notifications** in the menu. This will present you with all of the currently available notification agents. Click on each one individually to configure them. You must configure which type of notifications you want to send _per agent_. If no types are selected, you will not receive notifications! -Some agents may have specific configuration "gotchas" covered in their documentation pages. - -{% hint style="danger" %} -You will **not receive notifications** for any automatically approved requests unless the "Enable Notifications for Automatic Approvals" setting is enabled. -{% endhint %} +Note that some notifications are intended for the user who submitted the relevant request, while others are for administrators. For details, please see the documentation for the specific agent you would like to use. ## Requesting New Notification Agents diff --git a/docs/using-overseerr/notifications/discord.md b/docs/using-overseerr/notifications/discord.md new file mode 100644 index 000000000..a546ba38f --- /dev/null +++ b/docs/using-overseerr/notifications/discord.md @@ -0,0 +1,21 @@ +# Discord + +## Configuration + +{% hint style="info" %} +In order to configure Discord notifications, you first need to [create a webhook](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks). + +In order for users to be mentioned in Discord notifications, they must have their [Discord user ID](https://support.discord.com/hc/en-us/articles/206346498-Where-can-I-find-my-User-Server-Message-ID-) configured in their user settings. +{% endhint %} + +### Bot Username (optional) + +If you would like to override the name you configured for your bot in Discord, you may set this value to whatever you like! + +### Bot Avatar URL (optional) + +Similar to the bot username, you can override the avatar for your bot. + +### Webhook URL + +You can find the webhook URL in the Discord application, at **Server Settings → Integrations → Webhooks**. diff --git a/docs/using-overseerr/notifications/email.md b/docs/using-overseerr/notifications/email.md new file mode 100644 index 000000000..fd2c71c0f --- /dev/null +++ b/docs/using-overseerr/notifications/email.md @@ -0,0 +1,54 @@ +# Email + +{% hint style="info" %} +The following email notification types are sent to _all_ users with the **Manage Requests** permission, as these notification types are intended for application administrators rather than end users: + +- Media Requested +- Media Automatically Approved +- Media Failed + +On the other hand, the email notification types below are only sent to the user who submitted the request: + +- Media Approved +- Media Declined +- Media Available + +{% endhint %} + +## Configuration + +### Sender Address (required) + +Set this to the email address you would like to appear in the "from" field of the email message. + +Depending on your email provider, this may need to be an address you own. For example, Gmail requires this to be your actual email address. + +### Sender Name (optional) + +Configure a friendly name for the email sender. + +### SMTP Host + +Set this to the hostname or IP address of your SMTP host/server. + +### SMTP Port + +Set this to a supported port number for your SMTP host. `465` and `587` are commonly used. + +### Enable SSL (optional) + +This setting should only be enabled for ports that use [implicit SSL/TLS](https://tools.ietf.org/html/rfc8314) (e.g., port `465` in most cases). + +For servers that support [opportunistic TLS/STARTTLS](https://en.wikipedia.org/wiki/Opportunistic_TLS) (typically via port `587`), this setting should **not** be enabled. + +### SMTP Username & Password + +{% hint style="info" %} +If your account has two-factor authentication enabled, you may need to create an application password instead of using your account password. +{% endhint %} + +Configure these values as appropriate to authenticate with your SMTP host. + +### PGP Private Key & Password (optional) + +Configure these values to enable encrypting and signing of email messages using [OpenPGP](https://www.openpgp.org/). Note that individual users must also have their PGP public keys enabled in their user settings in order for PGP encryption to be used. diff --git a/docs/using-overseerr/notifications/webhooks.md b/docs/using-overseerr/notifications/webhooks.md index 68f546832..d1e912840 100644 --- a/docs/using-overseerr/notifications/webhooks.md +++ b/docs/using-overseerr/notifications/webhooks.md @@ -1,18 +1,20 @@ # Webhooks -Webhooks let you post a custom JSON payload to any endpoint you like. You can also set an authorization header for security purposes. +Webhooks allow you to send a custom JSON payload to any endpoint. You can also set an authorization header for security purposes. ## Configuration -The following configuration options are available: - ### Webhook URL (required) The URL you would like to post notifications to. Your JSON will be sent as the body of the request. -### Authorization Header +### Authorization Header (optional) + +{% hint style="info" %} +This is typically not needed. Please refer to your webhook provider's documentation for details. +{% endhint %} -Custom authorization header. Anything entered for this will be sent as an `Authorization` header. +This value will be sent as an `Authorization` HTTP header. ### JSON Payload (required)