From 89dd1f036f36ee07d0f3d53310e9826600124370 Mon Sep 17 00:00:00 2001 From: Jagandeep Brar Date: Mon, 3 May 2021 02:03:56 +0000 Subject: [PATCH] GitBook: [master] 24 pages modified --- docs/SUMMARY.md | 1 + .../notifications/custom-notifications.md | 189 ++++++++++++++++++ 2 files changed, 190 insertions(+) create mode 100644 docs/lunasea/notifications/custom-notifications.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index ae37350f..8af7450e 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -18,6 +18,7 @@ * [Radarr](lunasea/notifications/radarr.md) * [Sonarr](lunasea/notifications/sonarr.md) * [Tautulli](lunasea/notifications/tautulli.md) + * [Custom Notifications](lunasea/notifications/custom-notifications.md) * [Profiles](lunasea/profiles.md) ## Modules diff --git a/docs/lunasea/notifications/custom-notifications.md b/docs/lunasea/notifications/custom-notifications.md new file mode 100644 index 00000000..7c45063d --- /dev/null +++ b/docs/lunasea/notifications/custom-notifications.md @@ -0,0 +1,189 @@ +--- +description: Creating a custom notification for webhook-based push notifications +--- + +# Custom Notifications + +## Preparation + +{% hint style="warning" %} +Custom notifications are considered an advanced feature, and requires basic knowledge of JSON syntax and creating your own scripts/tools to handle sending the payloads. +{% endhint %} + +* Read through the main [Notifications](./) page +* Copy any module's device-based or user-based webhook URL from LunaSea + +You will need to slightly modify the webhook URL you have copied from any of the modules. Simply replace the name of the module within the webhook URL to `custom` and you're good to go! + +Alternatively, you can copy the content of the URL after the last slash \(after `device/` or `user/`\) to obtain your Firebase device or user identifier. + +## Endpoints + +Custom notifications are supported by both device-based and user-based notifications, with full endpoint details below: + +{% api-method method="post" host="https://notify.lunasea.app" path="/v1/custom/device/:device\_id" %} +{% api-method-summary %} +Device-Based +{% endapi-method-summary %} + +{% api-method-description %} +Send a custom notification using a device token to a single device running LunaSea. +{% endapi-method-description %} + +{% api-method-spec %} +{% api-method-request %} +{% api-method-path-parameters %} +{% api-method-parameter name="device\_id" type="string" required=true %} +The Firebase device identifier +{% endapi-method-parameter %} +{% endapi-method-path-parameters %} + +{% api-method-body-parameters %} +{% api-method-parameter name="title" type="string" required=true %} +The notification's title. +{% endapi-method-parameter %} + +{% api-method-parameter name="body" type="string" required=true %} +The notification's body content. +{% endapi-method-parameter %} + +{% api-method-parameter name="image" type="string" required=false %} +A **publicly accessible** URL to an image that will be attached to the notification. +{% endapi-method-parameter %} +{% endapi-method-body-parameters %} +{% endapi-method-request %} + +{% api-method-response %} +{% api-method-response-example httpCode=200 %} +{% api-method-response-example-description %} +Acknowledgement that the webhook has been received. + +_**This does not necessarily mean that the notification was successful**_, just that the relay has received the request and passed initial validation. +{% endapi-method-response-example-description %} + +```javascript +{ + "status": "OK" +} +``` +{% endapi-method-response-example %} + +{% api-method-response-example httpCode=500 %} +{% api-method-response-example-description %} +Will be returned when any other error occurs when trying to send the notification to your device. +{% endapi-method-response-example-description %} + +```javascript +{ + "status": "Internal Server Error" +} +``` +{% endapi-method-response-example %} +{% endapi-method-response %} +{% endapi-method-spec %} +{% endapi-method %} + + + +{% api-method method="post" host="https://notify.lunasea.app" path="/v1/custom/user/:user\_id" %} +{% api-method-summary %} +User-Based +{% endapi-method-summary %} + +{% api-method-description %} +Send a custom notification using a user token to all devices signed into that LunaSea account. +{% endapi-method-description %} + +{% api-method-spec %} +{% api-method-request %} +{% api-method-path-parameters %} +{% api-method-parameter name="user\_id" type="string" required=true %} +The Firebase user identifier +{% endapi-method-parameter %} +{% endapi-method-path-parameters %} + +{% api-method-body-parameters %} +{% api-method-parameter name="title" type="string" required=true %} +The notification's title. +{% endapi-method-parameter %} + +{% api-method-parameter name="body" type="string" required=true %} +The notification's body content. +{% endapi-method-parameter %} + +{% api-method-parameter name="image" type="string" required=false %} +A **publicly accessible** URL to an image that will be attached to the notification. +{% endapi-method-parameter %} +{% endapi-method-body-parameters %} +{% endapi-method-request %} + +{% api-method-response %} +{% api-method-response-example httpCode=200 %} +{% api-method-response-example-description %} +Acknowledgement that the webhook has been received. + +_**This does not necessarily mean that the notification was successful**_, just that the relay has received the request and passed initial validation. +{% endapi-method-response-example-description %} + +```javascript +{ + "status": "OK" +} +``` +{% endapi-method-response-example %} + +{% api-method-response-example httpCode=400 %} +{% api-method-response-example-description %} +Will be returned when no devices are found for a given user. Opening LunaSea on your device\(s\) should register the device automatically. +{% endapi-method-response-example-description %} + +```javascript +{ + "status": "No devices found" +} +``` +{% endapi-method-response-example %} + +{% api-method-response-example httpCode=404 %} +{% api-method-response-example-description %} +Will be returned when a user with the given identifier can not be found in LunaSea's authentication table. +{% endapi-method-response-example-description %} + +```javascript +{ + "status": "Invalid User ID" +} +``` +{% endapi-method-response-example %} + +{% api-method-response-example httpCode=500 %} +{% api-method-response-example-description %} +Will be returned when any other error occurs when trying to send the notification to the devices. +{% endapi-method-response-example-description %} + +```javascript +{ + "status": "Internal Server Error" +} +``` +{% endapi-method-response-example %} +{% endapi-method-response %} +{% endapi-method-spec %} +{% endapi-method %} + +## Basic Troubleshooting + +* Ensure that the required `title` parameter is a string type. + * If the type is not a string, the notification will fail. + * Sending no value or a null value will result in the title "Unknown Title" being used. +* Ensure that the required `body` parameter is a string type. + * If the type is not a string, the notification will fail. + * Sending no value or a null value will result in the body "Unknown Content" being used. +* If sending an image, ensure that the content is a valid URL. + * If the content is not a valid URL, the notification will fail. + * The URL must contain the protocol, `http://` or `https://`. + * The URL must be a direct link to the image and does not redirect. + * The URL must be publicly accessible, not requiring any authentication to access. +* If sending an image, the image must be a supported image type. + * Supported types include JPGs, PNGs, and animated GIFs. +