Debian Codegraph @

docs/services/specialized/notifiarr/index.md

raw
1 # Notifiarr
2
3 The Notifiarr service enables sending notifications through the Notifiarr API, which can forward notifications to various platforms including Discord.
4
5 Notifiarr acts as a notification relay service, allowing you to send notifications to multiple destinations through a single API endpoint.
6 It supports routing notifications to Discord channels and other configured services.
7
8 ## Configuration Options
9
10 | Parameter | Description | Required | Default |
11 |-------------|-----------------------------------------------|----------|----------|
12 | `apikey` | Your Notifiarr API key for authentication | Yes | - |
13 | `name` | Name of the app/script for notifications | No | Shoutrrr |
14 | `channel` | Discord channel ID for Discord notifications | No | - |
15 | `thumbnail` | Thumbnail image URL for Discord notifications | No | - |
16 | `image` | Image URL for Discord notifications | No | - |
17 | `color` | Color for Discord embed (6-digit hex) | No | - |
18
19 ## URL Format
20
21 !!! info ""
22 notifiarr://**`apikey`**?name=**`name`**&channel=**`channel`**&thumbnail=**`thumbnail`**&image=**`image`**&color=**`color`**
23
24 ### Complete URL Format
25
26 The full URL format supports all configuration parameters:
27
28 ```uri
29 notifiarr://[apikey]?name=[app_name]&channel=[channel_id]&thumbnail=[thumbnail_url]&image=[image_url]&color=[color_value]
30 ```
31
32 **Parameters:**
33
34 - `apikey` (required): Your Notifiarr API key
35 - `name` (optional): Name of the app/script for notifications (defaults to "Shoutrrr")
36 - `channel` (optional): Discord channel ID for routing notifications (numeric string)
37 - `thumbnail` (optional): Thumbnail image URL for Discord notifications
38 - `image` (optional): Image URL for Discord notifications
39 - `color` (optional): Color for Discord embed as 6-digit hex code (without # prefix) or color name
40
41 --8<-- "docs/services/specialized/notifiarr/config.md"
42
43 ## Usage Examples
44
45 ### Basic Notification
46
47 Send a simple notification using your Notifiarr API key:
48
49 !!! example
50 ```bash title="Send Basic Notification"
51 shoutrrr send --url "notifiarr://your-api-key-here" --message "Hello from Shoutrrr!"
52 ```
53
54 ```text title="Expected Output"
55 Notification sent
56 ```
57
58 ### Notification with Discord Channel
59
60 Send a notification that will be forwarded to a specific Discord channel:
61
62 !!! example
63 ```bash title="Send to Discord Channel"
64 shoutrrr send --url "notifiarr://your-api-key-here?channel=123456789012345678" --message "Alert: System status changed"
65 ```
66
67 ```text title="Expected Output"
68 Notification sent
69 ```
70
71 ### Notification with Thumbnail and Color
72
73 Send a notification with custom thumbnail and color:
74
75 !!! example
76 ```bash title="Send Notification with Thumbnail and Color"
77 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!"
78 ```
79
80 ```text title="Expected Output"
81 Notification sent
82 ```
83
84 ### Notification with Image
85
86 Send a notification with a custom image:
87
88 !!! example
89 ```bash title="Send Notification with Image"
90 shoutrrr send --url "notifiarr://your-api-key-here?channel=123456789012345678&image=https://example.com/chart.png" --title "Sales Report" --message "Monthly sales chart attached"
91 ```
92
93 ```text title="Expected Output"
94 Notification sent
95 ```
96
97 ### Notification with Thumbnail and Image
98
99 Send a notification with both thumbnail and image:
100
101 !!! example
102 ```bash title="Send Notification with Thumbnail and Image"
103 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"
104 ```
105
106 ```text title="Expected Output"
107 Notification sent
108 ```
109
110 ### Notification with User Mentions
111
112 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.
113
114 !!! example
115 ```bash title="Send Notification with User Mentions"
116 shoutrrr send --url "notifiarr://your-api-key-here?channel=123456789012345678" --message "Hey <@123456789> and <@!987654321>, the deployment is complete!"
117 ```
118
119 ```text title="Expected Output"
120 Notification sent
121 ```
122
123 ### Notification with Custom App Name
124
125 Send a notification with a custom app name:
126
127 !!! example
128 ```bash title="Send Notification with Custom App Name"
129 shoutrrr send --url "notifiarr://your-api-key-here?name=MyApp" --message "Hello from MyApp!"
130 ```
131
132 ```text title="Expected Output"
133 Notification sent
134 ```
135
136 ### Notification with Title
137
138 Send a notification with a custom title (appears in Discord embed):
139
140 !!! example
141 ```bash title="Send Notification with Title"
142 shoutrrr send --url "notifiarr://your-api-key-here?channel=123456789012345678" --title "System Alert" --message "Disk space running low on server"
143 ```
144
145 ```text title="Expected Output"
146 Notification sent
147 ```
148
149 ## API Documentation Reference
150
151 The Notifiarr service sends notifications to the Notifiarr API endpoint at `https://notifiarr.com/api/v1/notification/passthrough/{apikey}`.
152
153 ### Request Format
154
155 The service sends a POST request with a JSON payload containing the notification data. The payload structure follows the official Notifiarr API specification:
156
157 ```json
158 {
159 "notification": {
160 "name": "MyApp",
161 "event": "Optional event ID",
162 "update": null
163 },
164 "discord": {
165 "ids": {
166 "channel": 123456789012345678
167 },
168 "color": "Optional color (6-digit hex)",
169 "images": {
170 "thumbnail": "Optional thumbnail URL",
171 "image": "Optional image URL"
172 },
173 "text": {
174 "title": "Optional notification title",
175 "icon": "Optional icon URL",
176 "content": "Optional content text",
177 "description": "Your notification message",
178 "footer": "Optional footer text",
179 "fields": [
180 {
181 "title": "Field title",
182 "text": "Field content",
183 "inline": false
184 }
185 ]
186 },
187 "ping": {
188 "pingUser": 123456789,
189 "pingRole": 111111111
190 }
191 }
192 }
193 ```
194
195 #### Payload Structure Details
196
197 - **`notification`** (required): Core notification metadata
198 - `name`: Application identifier (configurable via `name` parameter, defaults to "Shoutrrr")
199 - `event`: Optional unique event ID from the `id` parameter
200 - `update`: Boolean flag to update existing messages with the same ID (optional, defaults to null)
201
202 - **`discord`** (optional): Discord-specific configuration (only included when channel is configured or other Discord fields are present)
203 - `ids.channel`: Discord channel ID (required when discord object is present)
204 - `color`: Optional embed color as 6-digit hex code (without # prefix)
205 - `images.thumbnail`: Optional thumbnail image URL
206 - `images.image`: Optional image URL
207 - `text.title`: Optional notification title from the `title` parameter
208 - `text.icon`: Optional icon URL for the embed
209 - `text.content`: Optional content text above the main message
210 - `text.description`: The notification message content
211 - `text.footer`: Optional footer text for the embed
212 - `text.fields`: Optional array of field objects with title, text, and inline properties
213 - `ping.pingUser`: Discord user ID to mention (parsed from the first `<@123>` mention in message)
214 - `ping.pingRole`: Discord role ID to mention (parsed from the first `<@&123>` mention in message)
215
216 ### Response
217
218 Successful requests return a 2xx status code. The service logs the server response for debugging purposes.
219
220 ### Error Handling
221
222 The service handles various error conditions:
223
224 - **Empty Message**: Returns an error if the message is empty
225 - **Invalid API Key**: Server returns authentication errors
226 - **Network Issues**: Connection timeouts or network failures
227 - **Server Errors**: Unexpected HTTP status codes from the Notifiarr API
228
229 ## Troubleshooting
230
231 ### Common Issues
232
233 #### Notifications not appearing in Discord
234
235 - **Check Channel ID**: Ensure the `channel` parameter contains a valid Discord channel ID (must be numeric)
236 - **Verify Permissions**: Confirm that Notifiarr has permission to post in the specified channel
237 - **API Key Validity**: Verify your Notifiarr API key is correct and active
238 - **Channel Configuration**: Ensure the channel parameter is included in the URL when Discord notifications are desired
239
240 #### Invalid color values
241
242 - **Color Format**: Colors must be provided as 6-digit hex codes (without # prefix) or valid color names
243 - **Example**: Use `color=FF0000` for red, not `color=#FF0000` or `color=red`
244
245 #### Thumbnail images not displaying
246
247 - **Valid URL**: Ensure the thumbnail URL is a valid, publicly accessible HTTPS URL
248 - **Image Format**: The URL should point directly to an image file (supported formats depend on Discord)
249
250 #### Image not displaying
251
252 - **Valid URL**: Ensure the image URL is a valid, publicly accessible HTTPS URL
253 - **Image Format**: The URL should point directly to an image file (supported formats depend on Discord)
254 - **Image Size**: Large images may be resized or may not display properly in Discord
255
256 ### Debugging Tips
257
258 - Enable verbose logging with `--debug` flag to see detailed request/response information
259 - Check Notifiarr server logs for additional error details
260 - Test with minimal configuration first, then add parameters incrementally
261
262 For more information about [Notifiarr](https://notifiarr.com/) and its capabilities, visit the [Notifiarr Wiki](https://notifiarr.wiki/).