diff --git a/docs/using-jellyseerr/notifications/gotify.md b/docs/using-jellyseerr/notifications/gotify.md new file mode 100644 index 000000000..6baaea9d7 --- /dev/null +++ b/docs/using-jellyseerr/notifications/gotify.md @@ -0,0 +1,21 @@ +--- +title: Gotify +description: Configure Gotify notifications. +sidebar_position: 5 +--- + +# Gotify + +## Configuration + +### Server URL + +Set this to the URL of your Gotify server. + +### Application Token + +Add an application to your Gotify server, and set this field to the generated application token. + +:::info +Please refer to the [Gotify API documentation](https://gotify.net/docs) for more details on configuring these notifications. +::: diff --git a/docs/using-jellyseerr/notifications/ntfy.md b/docs/using-jellyseerr/notifications/ntfy.md new file mode 100644 index 000000000..946dca781 --- /dev/null +++ b/docs/using-jellyseerr/notifications/ntfy.md @@ -0,0 +1,29 @@ +--- +title: ntfy.sh +description: Configure ntfy.sh notifications. +sidebar_position: 6 +--- + +# ntfy.sh + +## Configuration + +### Server Root URL + +Set this to the URL of your ntfy.sh server. + +### Topic + +Set this to the topic you want to send notifications to. + +### Username + Password authentication (optional) + +Set this to the username and password for your ntfy.sh server. + +### Token authentication (optional) + +Set this to the token for your ntfy.sh server. + +:::info +Please refer to the [ntfy.sh API documentation](https://docs.ntfy.sh/) for more details on configuring these notifications. +::: diff --git a/docs/using-jellyseerr/notifications/pushbullet.md b/docs/using-jellyseerr/notifications/pushbullet.md new file mode 100644 index 000000000..c9edf198e --- /dev/null +++ b/docs/using-jellyseerr/notifications/pushbullet.md @@ -0,0 +1,23 @@ +--- +title: Pushbullet +description: Configure Pushbullet notifications. +sidebar_position: 7 +--- + +# Pushbullet + +:::info +Users can optionally configure personal notifications in their user settings. + +User notifications are separate from system notifications, and the available notification types are dependent on user permissions. +::: + +## Configuration + +### Access Token + +[Create an access token](https://www.pushbullet.com/#settings) and set it here to grant Jellyseerr access to the Pushbullet API. + +### Channel Tag (optional) + +Optionally, [create a channel](https://www.pushbullet.com/my-channel) to allow other users to follow the notification feed using the specified channel tag. diff --git a/docs/using-jellyseerr/notifications/pushover.md b/docs/using-jellyseerr/notifications/pushover.md new file mode 100644 index 000000000..f0819e236 --- /dev/null +++ b/docs/using-jellyseerr/notifications/pushover.md @@ -0,0 +1,27 @@ +--- +title: Pushover +description: Configure Pushover notifications. +sidebar_position: 8 +--- + +# Pushover + +:::info +Users can optionally configure personal notifications in their user settings. + +User notifications are separate from system notifications, and the available notification types are dependent on user permissions. +::: + +## Configuration + +### Application/API Token + +[Register an application](https://pushover.net/apps/build) and enter the API token in this field. (You can use one of the [official icons in our GitHub repository](https://github.com/fallenbagel/jellyseerr/tree/develop/public) when configuring the application.) + +For more details on registering applications or the API token, please see the [Pushover API documentation](https://pushover.net/api#registration). + +### User Key + +Set this to the user key for your Pushover account. Alternatively, you can set this to a group key to deliver notifications to multiple users. + +For more details, please see the [Pushover API documentation](https://pushover.net/api#identifiers). diff --git a/docs/using-jellyseerr/notifications/slack.md b/docs/using-jellyseerr/notifications/slack.md new file mode 100644 index 000000000..50797a5b9 --- /dev/null +++ b/docs/using-jellyseerr/notifications/slack.md @@ -0,0 +1,17 @@ +--- +title: Slack +description: Configure Slack notifications. +sidebar_position: 9 +--- + +# Slack + +## Configuration + +### Webhook URL + +Simply [create a webhook](https://my.slack.com/services/new/incoming-webhook/) and enter the URL in this field. + +:::info +Please refer to the [Slack API documentation](https://api.slack.com/messaging/webhooks) for more details on configuring these notifications. +::: diff --git a/docs/using-jellyseerr/notifications/telegram.md b/docs/using-jellyseerr/notifications/telegram.md new file mode 100644 index 000000000..d90e5d3eb --- /dev/null +++ b/docs/using-jellyseerr/notifications/telegram.md @@ -0,0 +1,39 @@ +--- +title: Telegram +description: Configure Telegram notifications. +sidebar_position: 10 +--- + +# Telegram + +:::info +Users can optionally configure personal notifications in their user settings. + +User notifications are separate from system notifications, and the available notification types are dependent on user permissions. +::: + +## Configuration + +:::info +In order to configure Telegram notifications, you first need to [create a bot](https://telegram.me/BotFather). + +Bots **cannot** initiate conversations with users, so users must have your bot added to a conversation in order to receive notifications. +::: + +### Bot Username (optional) + +If this value is configured, users will be able to click a link to start a chat with your bot and configure their own personal notifications. + +The bot username should end with `_bot`, and the `@` prefix should be omitted. + +### Bot Authentication Token + +At the end of the bot creation process, [@BotFather](https://telegram.me/botfather) will provide an authentication token. + +### Chat ID + +To obtain your chat ID, simply create a new group chat, add [@get_id_bot](https://telegram.me/get_id_bot), and issue the `/my_id` command. + +### Send Silently (optional) + +Optionally, notifications can be sent silently. Silent notifications send messages without notification sounds. diff --git a/docs/using-jellyseerr/notifications/webhook.md b/docs/using-jellyseerr/notifications/webhook.md new file mode 100644 index 000000000..48951484c --- /dev/null +++ b/docs/using-jellyseerr/notifications/webhook.md @@ -0,0 +1,138 @@ +--- +title: Webhook +description: Configure webhook notifications. +sidebar_position: 4 +--- + +# Webhook + +The webhook notification agent enables you to send a custom JSON payload to any endpoint for specific notification events. + +## Configuration + +### Webhook URL + +The URL you would like to post notifications to. Your JSON will be sent as the body of the request. + +### Authorization Header (optional) + +:::info +This is typically not needed. Please refer to your webhook provider's documentation for details. +::: + +This value will be sent as an `Authorization` HTTP header. + +### JSON Payload + +Customize the JSON payload to suit your needs. Jellyseerr provides several [template variables](#template-variables) for use in the payload, which will be replaced with the relevant data when the notifications are triggered. + +## Template Variables + +### General + +| Variable | Value | +| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| `{{notification_type}}` | The type of notification (e.g. `MEDIA_PENDING` or `ISSUE_COMMENT`) | +| `{{event}}` | A friendly description of the notification event | +| `{{subject}}` | The notification subject (typically the media title) | +| `{{message}}` | The notification message body (the media overview/synopsis for request notifications; the issue description for issue notificatons) | +| `{{image}}` | The notification image (typically the media poster) | + +### Notify User + +These variables are for the target recipient of the notification. + +| Variable | Value | +| ---------------------------------------- | ------------------------------------------------------------- | +| `{{notifyuser_username}}` | The target notification recipient's username | +| `{{notifyuser_email}}` | The target notification recipient's email address | +| `{{notifyuser_avatar}}` | The target notification recipient's avatar URL | +| `{{notifyuser_settings_discordId}}` | The target notification recipient's Discord ID (if set) | +| `{{notifyuser_settings_telegramChatId}}` | The target notification recipient's Telegram Chat ID (if set) | + +:::info +The `notifyuser` variables are not defined for the following request notification types, as they are intended for application administrators rather than end users: + +- Request Pending Approval +- Request Automatically Approved +- Request Processing Failed + +On the other hand, the `notifyuser` variables _will_ be replaced with the requesting user's information for the below notification types: + +- Request Approved +- Request Declined +- Request Available + +If you would like to use the requesting user's information in your webhook, please instead include the relevant variables from the [Request](#request) section below. +::: + +### Special + +The following variables must be used as a key in the JSON payload (e.g., `"{{extra}}": []`). + +| Variable | Value | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------ | +| `{{media}}` | The relevant media object | +| `{{request}}` | The relevant request object | +| `{{issue}}` | The relevant issue object | +| `{{comment}}` | The relevant issue comment object | +| `{{extra}}` | The "extra" array of additional data for certain notifications (e.g., season/episode numbers for series-related notifications) | + +#### Media + +The `{{media}}` will be `null` if there is no relevant media object for the notification. + +These following special variables are only included in media-related notifications, such as requests. + +| Variable | Value | +| -------------------- | -------------------------------------------------------------------------------------------------------------- | +| `{{media_type}}` | The media type (`movie` or `tv`) | +| `{{media_tmdbid}}` | The media's TMDB ID | +| `{{media_tvdbid}}` | The media's TheTVDB ID | +| `{{media_status}}` | The media's availability status (`UNKNOWN`, `PENDING`, `PROCESSING`, `PARTIALLY_AVAILABLE`, or `AVAILABLE`) | +| `{{media_status4k}}` | The media's 4K availability status (`UNKNOWN`, `PENDING`, `PROCESSING`, `PARTIALLY_AVAILABLE`, or `AVAILABLE`) | + +#### Request + +The `{{request}}` will be `null` if there is no relevant media object for the notification. + +The following special variables are only included in request-related notifications. + +| Variable | Value | +| ----------------------------------------- | ----------------------------------------------- | +| `{{request_id}}` | The request ID | +| `{{requestedBy_username}}` | The requesting user's username | +| `{{requestedBy_email}}` | The requesting user's email address | +| `{{requestedBy_avatar}}` | The requesting user's avatar URL | +| `{{requestedBy_settings_discordId}}` | The requesting user's Discord ID (if set) | +| `{{requestedBy_settings_telegramChatId}}` | The requesting user's Telegram Chat ID (if set) | + +#### Issue + +The `{{issue}}` will be `null` if there is no relevant media object for the notification. + +The following special variables are only included in issue-related notifications. + +| Variable | Value | +| ---------------------------------------- | ----------------------------------------------- | +| `{{issue_id}}` | The issue ID | +| `{{reportedBy_username}}` | The requesting user's username | +| `{{reportedBy_email}}` | The requesting user's email address | +| `{{reportedBy_avatar}}` | The requesting user's avatar URL | +| `{{reportedBy_settings_discordId}}` | The requesting user's Discord ID (if set) | +| `{{reportedBy_settings_telegramChatId}}` | The requesting user's Telegram Chat ID (if set) | + +#### Comment + +The `{{comment}}` will be `null` if there is no relevant media object for the notification. + +The following special variables are only included in issue comment-related notifications. + +| Variable | Value | +| ----------------------------------------- | ----------------------------------------------- | +| `{{comment_message}}` | The comment message | +| `{{commentedBy_username}}` | The commenting user's username | +| `{{commentedBy_email}}` | The commenting user's email address | +| `{{commentedBy_avatar}}` | The commenting user's avatar URL | +| `{{commentedBy_settings_discordId}}` | The commenting user's Discord ID (if set) | +| `{{commentedBy_settings_telegramChatId}}` | The commenting user's Telegram Chat ID (if set) |