# Notifiarr The Notifiarr service enables sending notifications through the Notifiarr API, which can forward notifications to various platforms including Discord. Notifiarr acts as a notification relay service, allowing you to send notifications to multiple destinations through a single API endpoint. It supports routing notifications to Discord channels and other configured services. ## Configuration Options | Parameter | Description | Required | Default | |-------------|-----------------------------------------------|----------|----------| | `apikey` | Your Notifiarr API key for authentication | Yes | - | | `name` | Name of the app/script for notifications | No | Shoutrrr | | `channel` | Discord channel ID for Discord notifications | No | - | | `thumbnail` | Thumbnail image URL for Discord notifications | No | - | | `image` | Image URL for Discord notifications | No | - | | `color` | Color for Discord embed (6-digit hex) | No | - | ## URL Format !!! info "" notifiarr://**`apikey`**?name=**`name`**&channel=**`channel`**&thumbnail=**`thumbnail`**&image=**`image`**&color=**`color`** ### Complete URL Format The full URL format supports all configuration parameters: ```uri notifiarr://[apikey]?name=[app_name]&channel=[channel_id]&thumbnail=[thumbnail_url]&image=[image_url]&color=[color_value] ``` **Parameters:** - `apikey` (required): Your Notifiarr API key - `name` (optional): Name of the app/script for notifications (defaults to "Shoutrrr") - `channel` (optional): Discord channel ID for routing notifications (numeric string) - `thumbnail` (optional): Thumbnail image URL for Discord notifications - `image` (optional): Image URL for Discord notifications - `color` (optional): Color for Discord embed as 6-digit hex code (without # prefix) or color name --8<-- "docs/services/specialized/notifiarr/config.md" ## Usage Examples ### Basic Notification Send a simple notification using your Notifiarr API key: !!! example ```bash title="Send Basic Notification" shoutrrr send --url "notifiarr://your-api-key-here" --message "Hello from Shoutrrr!" ``` ```text title="Expected Output" Notification sent ``` ### Notification with Discord Channel Send a notification that will be forwarded to a specific Discord channel: !!! example ```bash title="Send to Discord Channel" shoutrrr send --url "notifiarr://your-api-key-here?channel=123456789012345678" --message "Alert: System status changed" ``` ```text title="Expected Output" Notification sent ``` ### Notification with Thumbnail and Color Send a notification with custom thumbnail and color: !!! example ```bash title="Send Notification with Thumbnail and Color" shoutrrr send --url "notifiarr://your-api-key-here?channel=123456789012345678&thumbnail=https://example.com/alert.png&color=FF0000" --title "Critical Alert" --message "Server is down!" ``` ```text title="Expected Output" Notification sent ``` ### Notification with Image Send a notification with a custom image: !!! example ```bash title="Send Notification with Image" shoutrrr send --url "notifiarr://your-api-key-here?channel=123456789012345678&image=https://example.com/chart.png" --title "Sales Report" --message "Monthly sales chart attached" ``` ```text title="Expected Output" Notification sent ``` ### Notification with Thumbnail and Image Send a notification with both thumbnail and image: !!! example ```bash title="Send Notification with Thumbnail and Image" shoutrrr send --url "notifiarr://your-api-key-here?channel=123456789012345678&thumbnail=https://example.com/icon.png&image=https://example.com/full-image.png" --title "Product Update" --message "New product launch details" ``` ```text title="Expected Output" Notification sent ``` ### Notification with User Mentions Send a notification that mentions specific Discord users (parsed from message content). Both standard mentions `<@123>` and nickname mentions `<@!456>` are supported. **Note:** Only the first user mention and first role mention in the message will be used for pinging. !!! example ```bash title="Send Notification with User Mentions" shoutrrr send --url "notifiarr://your-api-key-here?channel=123456789012345678" --message "Hey <@123456789> and <@!987654321>, the deployment is complete!" ``` ```text title="Expected Output" Notification sent ``` ### Notification with Custom App Name Send a notification with a custom app name: !!! example ```bash title="Send Notification with Custom App Name" shoutrrr send --url "notifiarr://your-api-key-here?name=MyApp" --message "Hello from MyApp!" ``` ```text title="Expected Output" Notification sent ``` ### Notification with Title Send a notification with a custom title (appears in Discord embed): !!! example ```bash title="Send Notification with Title" shoutrrr send --url "notifiarr://your-api-key-here?channel=123456789012345678" --title "System Alert" --message "Disk space running low on server" ``` ```text title="Expected Output" Notification sent ``` ## API Documentation Reference The Notifiarr service sends notifications to the Notifiarr API endpoint at `https://notifiarr.com/api/v1/notification/passthrough/{apikey}`. ### Request Format The service sends a POST request with a JSON payload containing the notification data. The payload structure follows the official Notifiarr API specification: ```json { "notification": { "name": "MyApp", "event": "Optional event ID", "update": null }, "discord": { "ids": { "channel": 123456789012345678 }, "color": "Optional color (6-digit hex)", "images": { "thumbnail": "Optional thumbnail URL", "image": "Optional image URL" }, "text": { "title": "Optional notification title", "icon": "Optional icon URL", "content": "Optional content text", "description": "Your notification message", "footer": "Optional footer text", "fields": [ { "title": "Field title", "text": "Field content", "inline": false } ] }, "ping": { "pingUser": 123456789, "pingRole": 111111111 } } } ``` #### Payload Structure Details - **`notification`** (required): Core notification metadata - `name`: Application identifier (configurable via `name` parameter, defaults to "Shoutrrr") - `event`: Optional unique event ID from the `id` parameter - `update`: Boolean flag to update existing messages with the same ID (optional, defaults to null) - **`discord`** (optional): Discord-specific configuration (only included when channel is configured or other Discord fields are present) - `ids.channel`: Discord channel ID (required when discord object is present) - `color`: Optional embed color as 6-digit hex code (without # prefix) - `images.thumbnail`: Optional thumbnail image URL - `images.image`: Optional image URL - `text.title`: Optional notification title from the `title` parameter - `text.icon`: Optional icon URL for the embed - `text.content`: Optional content text above the main message - `text.description`: The notification message content - `text.footer`: Optional footer text for the embed - `text.fields`: Optional array of field objects with title, text, and inline properties - `ping.pingUser`: Discord user ID to mention (parsed from the first `<@123>` mention in message) - `ping.pingRole`: Discord role ID to mention (parsed from the first `<@&123>` mention in message) ### Response Successful requests return a 2xx status code. The service logs the server response for debugging purposes. ### Error Handling The service handles various error conditions: - **Empty Message**: Returns an error if the message is empty - **Invalid API Key**: Server returns authentication errors - **Network Issues**: Connection timeouts or network failures - **Server Errors**: Unexpected HTTP status codes from the Notifiarr API ## Troubleshooting ### Common Issues #### Notifications not appearing in Discord - **Check Channel ID**: Ensure the `channel` parameter contains a valid Discord channel ID (must be numeric) - **Verify Permissions**: Confirm that Notifiarr has permission to post in the specified channel - **API Key Validity**: Verify your Notifiarr API key is correct and active - **Channel Configuration**: Ensure the channel parameter is included in the URL when Discord notifications are desired #### Invalid color values - **Color Format**: Colors must be provided as 6-digit hex codes (without # prefix) or valid color names - **Example**: Use `color=FF0000` for red, not `color=#FF0000` or `color=red` #### Thumbnail images not displaying - **Valid URL**: Ensure the thumbnail URL is a valid, publicly accessible HTTPS URL - **Image Format**: The URL should point directly to an image file (supported formats depend on Discord) #### Image not displaying - **Valid URL**: Ensure the image URL is a valid, publicly accessible HTTPS URL - **Image Format**: The URL should point directly to an image file (supported formats depend on Discord) - **Image Size**: Large images may be resized or may not display properly in Discord ### Debugging Tips - Enable verbose logging with `--debug` flag to see detailed request/response information - Check Notifiarr server logs for additional error details - Test with minimal configuration first, then add parameters incrementally For more information about [Notifiarr](https://notifiarr.com/) and its capabilities, visit the [Notifiarr Wiki](https://notifiarr.wiki/).