|
| 1 | +# Ntfy Binding |
| 2 | + |
| 3 | +The Ntfy binding enables openHAB to publish notifications to Ntfy-compatible servers (for example [ntfy.sh](https://ntfy.sh) or a self-hosted ntfy-compatible endpoint). |
| 4 | + |
| 5 | +Ntfy is a simple HTTP-based notification service and message broker; see [ntfy.sh](https://ntfy.sh) for details and public servers. |
| 6 | + |
| 7 | +It is intended for integrations where openHAB should push alert or informational messages to mobile or desktop clients that support the Ntfy protocol. |
| 8 | +The binding supports basic text messages as well as common rich features supported by the protocol: message priority, tags, icon URLs, attachments, click actions and simple action buttons |
| 9 | + |
| 10 | +Typical uses include doorbell alerts, security notifications, system health messages, or any automation that should notify users in real time via an Ntfy-compatible notification channel. |
| 11 | + |
| 12 | +## Supported Things |
| 13 | + |
| 14 | +This binding provides the following Thing types: |
| 15 | + |
| 16 | +- `server` (bridge) — Represents a connection to an Ntfy server. The bridge holds shared connection settings (hostname, username, password, connectionTimeout) which are used by topic Things. |
| 17 | +- `ntfy-topic` (Thing) — Represents a topic/channel on a configured Ntfy server. Each topic Thing must be associated with a `server` bridge. |
| 18 | + |
| 19 | +## Thing Configuration |
| 20 | + |
| 21 | +### `server` Bridge Configuration |
| 22 | + |
| 23 | +| Name | Type | Description | Default | Required | Advanced | |
| 24 | +|-------------------|---------|------------------------------------------------------------------------------------------|------------------------------------|----------|----------| |
| 25 | +| hostname | text | Base URL of the ntfy server | [https://ntfy.sh](https://ntfy.sh) | yes | no | |
| 26 | +| username | text | Optional username for basic auth | N/A | no | no | |
| 27 | +| password | text | Optional password - if username is provided basic auth is used else Bearer token is used | N/A | no | no | |
| 28 | +| connectionTimeout | integer | WebSocket / HTTP connection timeout ms | 60000 | no | yes | |
| 29 | + |
| 30 | +Configure the `server` as a bridge to hold shared server and authentication settings. |
| 31 | +For authentication with access token only set the password and leave the username empty. |
| 32 | + |
| 33 | +### `ntfy-topic` Thing Configuration |
| 34 | + |
| 35 | +| Name | Type | Description | Default | Required | Advanced | |
| 36 | +|-----------|------|---------------------------|---------|----------|----------| |
| 37 | +| topicName | text | Name of the topic/channel | N/A | yes | no | |
| 38 | + |
| 39 | +## Channels |
| 40 | + |
| 41 | +### `ntfy-topic` Channels |
| 42 | + |
| 43 | +| Channel | Type | Read/Write | Description | |
| 44 | +|-------------------|----------|------------|---------------------------------------------| |
| 45 | +| last-message | String | R | Last received message payload (read-only) | |
| 46 | +| last-message-time | DateTime | R | Timestamp of the last message (read-only) | |
| 47 | +| last-message-id | String | R | ID of the last message (read-only) | |
| 48 | + |
| 49 | +## Full Example |
| 50 | + |
| 51 | +Below are examples for textual configuration files showing a bridge (`server`), a topic Thing (`ntfy-topic`), Items bound to the Thing's channels, and a simple sitemap to display the last message and its timestamp. |
| 52 | + |
| 53 | +### Thing Configuration |
| 54 | + |
| 55 | +```java |
| 56 | +Bridge ntfy:server:myConn "Ntfy Server" [ hostname="https://ntfy.sh", connectionTimeout=60000, username="ntfyUser", password="MyPaSsWoRd"] |
| 57 | + |
| 58 | +Thing ntfy:ntfy-topic:home "Front Door Notifications" (ntfy:server:myConn) [ topicName="home" ] |
| 59 | +``` |
| 60 | + |
| 61 | +### Item Configuration (items file) |
| 62 | + |
| 63 | +Bind Items to the read-only channels exposed by the topic Thing to show the last received message and its timestamp: |
| 64 | + |
| 65 | +```java |
| 66 | +String FrontDoorLastMessage "Front Door Message" { channel="ntfy:ntfy-topic:home:last-message" } |
| 67 | +DateTime FrontDoorMessageTime "Last message received" { channel="ntfy:ntfy-topic:home:last-message-time" } |
| 68 | +``` |
| 69 | + |
| 70 | +Note: Sending notifications from openHAB to ntfy is done via the binding's Actions from rules (the binding exposes Actions to publish/delete messages). The channels above are read-only and show incoming or last-state values. |
| 71 | + |
| 72 | +### Sitemap Configuration (sitemap file) |
| 73 | + |
| 74 | +Simple sitemap demonstrating how to display the last message and its timestamp: |
| 75 | + |
| 76 | +```perl |
| 77 | + sitemap notifications label="Notifications" |
| 78 | +{ |
| 79 | + <Frame label="Front Door"> |
| 80 | + Text item=FrontDoorLastMessage label="Last message [%s]" |
| 81 | + Text item=FrontDoorMessageTime label="Received [%1$td.%1$tm.%1$tY %1$tR]" |
| 82 | + </Frame> |
| 83 | +} |
| 84 | +``` |
| 85 | + |
| 86 | +## Actions (Rules DSL and JavaScript) |
| 87 | + |
| 88 | +This binding exposes Rule Actions to send and manage messages on a configured topic. |
| 89 | +Actions are available for use from the Rules DSL and the ECMAScript/JavaScript automation scripts. |
| 90 | +The actions support a builder-style API to configure a message (message text, priority, tags, icon, attachments, actions, sequence id, ...) and then send it. |
| 91 | + |
| 92 | +Important: Always check that the Thing exist before invoking methods. |
| 93 | + |
| 94 | +### Available action methods |
| 95 | + |
| 96 | +Below is a quick reference of the builder-style methods provided by the binding actions. Use these to construct messages before calling `send()`. |
| 97 | + |
| 98 | +| Method | Parameters | Description | Ntfy docs | |
| 99 | +|-------------------------|---------------------------------------------------------------------------------------------------|----------------------------------------------------------------------|------------------------------------------------------------------------------| |
| 100 | +| withMessage | (String message) | Set the main message text. | [publish](https://docs.ntfy.sh/publish) | |
| 101 | +| withPriority | (int priority) | Set message priority (1-5). | [priority](https://ntfy.sh/docs/publish/#priority) | |
| 102 | +| withTitle | (String title) | Set title. | [title](https://docs.ntfy.sh/publish/#message-title) | |
| 103 | +| withTag | (String tag) | Add a tag to the message. | [tags](https://ntfy.sh/docs/publish/#tags) | |
| 104 | +| withIcon | (String url) | Set an icon URL for the notification. | [icons](https://ntfy.sh/docs/publish/#icons) | |
| 105 | +| withAttachment | (String url, String filename) | Attach a file or resource URL with optional filename. | [attachments](https://docs.ntfy.sh/publish/#attach-file-from-a-url) | |
| 106 | +| withViewAction | (String label, Boolean clearNotification, String url) | Add a view action (opens URL) with optional clear flag. | [actions](https://docs.ntfy.sh/publish/#open-websiteapp) | |
| 107 | +| withCopyAction | (String label, Boolean clearNotification, String value) | Add an action that copies text to clipboard on the client. | [actions](https://docs.ntfy.sh/publish/#copy-to-clipboard) | |
| 108 | +| withHttpAction | (String label, Boolean clearNotification, String url, String method, String headers, String body) | Add an HTTP action with optional method, headers and body. | [actions](https://docs.ntfy.sh/publish/#send-http-request) | |
| 109 | +| withBroadcastAction | (String label, Boolean clearNotification, String params) | Add a broadcast action to trigger local apps/handlers. | [actions](https://docs.ntfy.sh/publish/#send-android-broadcast) | |
| 110 | +| withDelay | (String delay) | Assign a delay. | [delay](https://docs.ntfy.sh/publish/#scheduled-delivery) | |
| 111 | +| withSequenceId | (String sequenceId) | Assign a sequence id for later reference (useful for delete/update). | [sequence id](https://docs.ntfy.sh/publish/#updating-deleting-notifications) | |
| 112 | +| send | () | Send the built message; returns a message ID string. | [publish](https://ntfy.sh/docs/publish/) | |
| 113 | +| send | (String file, String filename, String sequenceId) | Send a file; returns a message ID string. | [publish_local_file](https://docs.ntfy.sh/publish/#attach-local-file) | |
| 114 | +| delete | (String sequenceId) | Delete a message previously sent with the given sequence id. | [delete](https://ntfy.sh/docs/publish/#deleting-notifications) | |
| 115 | +| clearNtfyMessageBuilder | () | Reset the message build explicitly | | |
| 116 | + |
| 117 | +For more information about ntfy features and the notification format, see the ntfy project documentation: [https://ntfy.sh/docs/](https://ntfy.sh/docs/) |
| 118 | + |
| 119 | +### Rules DSL example |
| 120 | + |
| 121 | +```rules |
| 122 | +// Obtain the Thing-specific actions and use the builder to send a message |
| 123 | +val bindingActions = getActions("ntfy", "ntfy:ntfy-topic:frontdoor") |
| 124 | +if (bindingActions !== null) { |
| 125 | + // simple one-liner: send a message |
| 126 | + val msgId = bindingActions.withMessage("Someone is at the door").withPriority(4).send() |
| 127 | +
|
| 128 | + // or build up a more complex message |
| 129 | + bindingActions.withMessage("Doorbell pressed") |
| 130 | + .withSequenceId("doorbell-1") |
| 131 | + .withTag("door") |
| 132 | + .withIcon("https://example.org/icons/door.png") |
| 133 | + .withViewAction("Open UI", true, "https://example.org/ui") |
| 134 | + .send() |
| 135 | +
|
| 136 | + // delete a previously sent message by sequence id |
| 137 | + bindingActions.delete("doorbell-1") |
| 138 | +} |
| 139 | +``` |
| 140 | + |
| 141 | +The builder methods available include: withMessage(String), withPriority(int), withTag(String), withIcon(String), withAttachment(String, String), withViewAction(...), withCopyAction(...), withHttpAction(...), withBroadcastAction(...), withSequenceId(String), send(), and delete(String). |
| 142 | + |
| 143 | +### ECMAScript / JavaScript example |
| 144 | + |
| 145 | +In ECMAScript scripts you can obtain the Thing Actions and use the same builder API. The example below assumes the automation engine provides an `actions` helper (typical in openHAB JavaScript environment): |
| 146 | + |
| 147 | +```javascript |
| 148 | +// get the Thing actions for the topic Thing |
| 149 | +var bindingActions = actions.get("ntfy", "ntfy:ntfy-topic:frontdoor"); |
| 150 | +if (bindingActions) { |
| 151 | + // send a simple message |
| 152 | + var id = bindingActions.withMessage("Garage opened").withPriority(3).send(); |
| 153 | + |
| 154 | + // build and send a message with extra features |
| 155 | + bindingActions.withMessage("Motion detected in garage") |
| 156 | + .withSequenceId("garage-1") |
| 157 | + .withTag("motion") |
| 158 | + .withHttpAction("Open Camera", true, "https://camera/local/snap", "POST", null, null) |
| 159 | + .send(); |
| 160 | +} |
| 161 | +``` |
| 162 | + |
| 163 | +If your scripting environment exposes a different API to retrieve Thing Actions, adapt the call accordingly. The important part is to obtain the Thing-specific actions object for the binding and then use the builder methods shown above. |
0 commit comments