Debian Codegraph @

docs/services/push/ntfy/index.md

raw
1 # Ntfy
2
3 Upstream docs: <https://docs.ntfy.sh/publish/>
4
5 ## URL Format
6
7 !!! info ""
8 ntfy://__`host`__/__`topic`__?priority=__`priority`__&tags=__`tag1`__,__`tag2`__&title=__`title`__
9
10 --8<-- "docs/services/push/ntfy/config.md"
11
12 ## Getting Started
13
14 Ntfy supports both the public [ntfy.sh](https://ntfy.sh) service and self-hosted instances. For the public service, simply use `ntfy.sh` as the host. For self-hosted instances, specify your server's hostname and port.
15
16 !!! example "Public ntfy.sh service"
17 ```uri
18 ntfy://ntfy.sh/mytopic
19 ```
20
21 !!! example "Self-hosted instance"
22 ```uri
23 ntfy://my-ntfy-server.com:8080/mytopic
24 ```
25
26 Topics are user-defined and can be any string. For authentication, include username and password in the URL if your ntfy server requires it.
27
28 ## Features
29
30 Ntfy offers several advanced features that enhance notification capabilities:
31
32 - __Action Buttons__: Add interactive buttons to notifications that can trigger HTTP requests, open URLs, or broadcast intents
33 - __Attachments__: Send files and images as attachments via URL or direct upload
34 - __Delayed Delivery__: Schedule notifications for future delivery using timestamps or duration strings
35 - __Email Notifications__: Forward notifications to email addresses for additional reach
36 - __Priority Levels__: Set message priority from 1 (min) to 5 (max) to control notification behavior
37 - __Tags and Emojis__: Add tags that automatically map to emojis for visual enhancement
38 - __Click Actions__: Specify URLs that open when notifications are tapped
39 - __Message Caching__: Control whether messages are cached for offline delivery
40
41 For complete feature documentation, see the [ntfy publish documentation](https://docs.ntfy.sh/publish/).
42
43 ## Optional Parameters
44
45 Commonly used parameters can be added as query parameters to customize notifications:
46
47 - __`priority`__: Message priority level (1-5, where 1=min, 3=default, 5=max)
48 - __`title`__: Custom title for the notification
49 - __`tags`__: Comma-separated list of tags (e.g., `warning,alert` maps to ⚠️🚨)
50 - __`actions`__: JSON array of action buttons (see [action buttons docs](https://docs.ntfy.sh/publish/#action-buttons))
51 - __`delay`__: Schedule delivery (e.g., `5m` for 5 minutes, `2023-12-31T23:59:59Z` for specific time)
52 - __`email`__: Email address to send notification to
53 - __`click`__: URL to open when notification is clicked
54
55 !!! example "High-priority notification with tags"
56 ```uri
57 ntfy://ntfy.sh/alerts?priority=5&tags=warning,fire&title=System+Alert
58 ```
59
60 !!! note
61 Action buttons require JSON formatting. See the [upstream documentation](https://docs.ntfy.sh/publish/#action-buttons) for detailed syntax.
62
63 ## TLS Configuration
64
65 Ntfy supports two TLS-related configuration options to handle different security scenarios:
66
67 - **`DisableTLSVerification`**: When set to `true`, disables TLS certificate verification. This allows connections to servers with self-signed or invalid certificates, but still uses the HTTPS protocol. Use this option when you trust the server but the certificate cannot be verified by standard means.
68
69 - **`DisableTLS`**: When set to `true`, disables TLS entirely and forces the use of the HTTP scheme instead of HTTPS. This makes the connection unencrypted and should only be used in secure, trusted environments or for testing purposes.
70
71 !!! warning
72 Using either of these options reduces the security of your connection. `DisableTLS` is particularly insecure as it transmits data in plain text. Only use these options when necessary and in controlled environments.
73
74 ## Examples
75
76 !!! example "Basic notification"
77 ```uri
78 ntfy://ntfy.sh/mytopic
79 ```
80
81 !!! example "With authentication"
82 ```uri
83 ntfy://username:[email protected]/privatetopic
84 ```
85
86 !!! example "With parameters"
87 ```uri
88 ntfy://ntfy.sh/updates?priority=4&tags=info,computer&title=Server+Update
89 ```
90
91 !!! example "Delayed notification"
92 ```uri
93 ntfy://ntfy.sh/reminders?delay=1h&title=Meeting+in+1+hour
94 ```
95
96 !!! example "With action button"
97 ```uri
98 ntfy://ntfy.sh/tasks?actions=[{"action":"view","label":"Open Dashboard","url":"https://dashboard.example.com"}]&title=Task+Completed
99 ```