node-red-contrib-ntfy

⚠️ AI-GENERATED — NOT MAINTAINED

This package was generated by an AI assistant (Claude by Anthropic) as part of a home-server automation project. It is provided as-is with no warranty, no active maintenance, and no guarantee of correctness or security.

Use at your own risk. Review the source code before deploying on any system you care about. Pull requests and forks are welcome but there is no commitment to respond to issues.

Node-RED nodes for publishing and subscribing to ntfy notification topics. Supports self-hosted and cloud ntfy instances, all ntfy publish features, and runtime configuration via msg.ntfyOptions.

Nodes

| Node | Description | |---|---| | ntfy-config | Shared configuration — server URL and credentials | | ntfy-send | Publish a notification to a topic | | ntfy-watch | Poll a topic on a fixed interval and emit incoming notifications |

Installation

Via Node-RED Palette Manager

Search for node-red-contrib-ntfy in the Manage Palette dialog.

Via npm (in your Node-RED user directory)

cd ~/.node-red
npm install node-red-contrib-ntfy

Local install for development

cd ~/.node-red
npm install /path/to/node-red-contrib-ntfy

Requirements

• Node-RED 3.0 or later
• Node.js 18 or later
• A running ntfy server (self-hosted via Docker or ntfy.sh)

Quick start

1. Add an ntfy-config node (via the Server dropdown in any ntfy node)
2. Set the server URL — e.g. http://ntfy:80 for a local Docker instance
3. Choose an auth type and fill in credentials if required
4. Drop an ntfy-send node, set a topic and connect msg.payload as the body
5. Drop an ntfy-watch node on the same topic to receive notifications

ntfy-config

Shared configuration node. Not placed on the canvas — referenced by ntfy-send and ntfy-watch via a Server dropdown.

Auth type

| Type | Description | |---|---| | None | No authentication. Suitable for local instances with open topics. | | Username & password | HTTP Basic auth. Credentials sent as a Base64-encoded Authorization header. | | Access token | Bearer token auth. Create tokens in the ntfy web UI or CLI. Tokens typically start with tk_. |

Extra headers

An optional field available regardless of which auth type is chosen. Supply arbitrary Key: Value headers one per line. Applied on top of the chosen auth type. Useful for reverse-proxy authentication schemes or any custom headers your ntfy setup requires.

X-Custom-Header: value
Another-Header: value

ntfy-send

Publish a notification to an ntfy topic when a message is received.

The message body comes from msg.payload unless msg.ntfyOptions.message is set.

All string fields in the node editor support Mustache templates resolved against the incoming message at runtime. For example, set Topic to {{payload.topic}} to use a dynamic topic from the message.

Node editor fields

| Field | ntfy header | Description | |---|---|---| | Topic | URL path | Target topic name. Required. Mustache supported. | | Title | Title | Notification title. Defaults to topic URL if blank. | | Priority | Priority | 1 (min) to 5 (urgent/max). Default 3. | | Tags | Tags | Comma-separated emoji shortcodes or plain tags. | | Click URL | Click | URL opened when the notification is tapped. | | Icon URL | Icon | URL of a notification icon image. | | Attach URL | Attach | Attach an image or file from a URL. | | Filename | Filename | Override the filename for the attachment. | | Actions | Actions | Action button definitions (see ntfy docs). | | Forward email | Email | Forward the notification to this email address. | | Delay | Delay | Schedule delivery e.g. 30min, tomorrow, 9am. | | Markdown | Markdown | Enable Markdown rendering in the notification body. | | Cache | Cache | Override server caching: yes or no. | | Firebase | Firebase | Override Firebase delivery: yes or no. |

Runtime override — msg.ntfyOptions

Set msg.ntfyOptions to override any field at runtime. All fields optional. Takes priority over node editor settings and Mustache templates.

msg.ntfyOptions = {
    // Core
    topic:    "alerts",
    message:  "Custom body",   // overrides msg.payload
    title:    "Alert",
    priority: 4,               // 1–5 or "min"/"low"/"default"/"high"/"urgent"/"max"
    tags:     ["warning"],     // array or comma-separated string

    // Formatting
    markdown: true,

    // Actions
    click:    "https://example.com",
    icon:     "https://example.com/icon.png",
    actions:  "view, Open dashboard, https://example.com",

    // Attachment (URL only — local file upload not supported)
    attach:   "https://example.com/photo.jpg",
    filename: "photo.jpg",

    // Scheduling
    delay:    "30min",

    // Forwarding
    email:    "[email protected]",

    // Advanced
    cache:    "no",
    firebase: "no",
    id:       "msg-abc123"     // for updating/deleting existing messages
};

Output

On success the original message passes through with msg.ntfyResponse set to the parsed JSON response from the ntfy server.

Status

| Colour | Shape | Meaning | |---|---|---| | Blue | Dot | Sending | | Green | Dot | Sent successfully | | Red | Dot | Error — check debug panel |

ntfy-watch

Poll an ntfy topic on a fixed interval and emit a message for each new notification. Starts automatically on deploy.

Tracks the last seen message ID as a watermark — only messages newer than the last emitted message are returned on each poll. No messages are missed as long as they remain in ntfy's cache (default 12 hours on self-hosted instances).

Node editor fields

| Field | Description | |---|---| | Topic(s) | Single topic or comma-separated list e.g. alerts,warnings | | Poll every | Seconds between polls (default 30) | | Message filter | Server-side: only deliver messages containing this text | | Title filter | Server-side: only deliver messages with this title | | Priority filter | Server-side: e.g. 4,5 or high,urgent | | Tags filter | Server-side: only deliver messages with this tag |

Output message properties

| Property | Type | Description | |---|---|---| | msg.payload | string | Notification message body | | msg.ntfyTopic | string | Topic the message arrived on | | msg.ntfyTitle | string | Notification title (empty if not set) | | msg.ntfyPriority | number | Priority 1–5 | | msg.ntfyTags | array | Tag strings | | msg.ntfyClick | string | Click URL (empty if not set) | | msg.ntfyIcon | string | Icon URL (empty if not set) | | msg.ntfyActions | array | Action button objects | | msg.ntfyAttachment | object|null | Attachment details or null | | msg.ntfyId | string | Unique message ID | | msg.ntfyTime | number | Unix timestamp (seconds) | | msg.ntfyEvent | string | Always "message" | | msg.ntfyRaw | object | Full raw event from the ntfy API |

Runtime control — send into this node

Wire an Inject node into ntfy-watch to control polling at runtime.

// Stop polling (watermark is preserved)
msg.payload = "stop";

// Resume from last seen message ID
msg.payload = "start";

// Reset watermark to now and restart (old messages not replayed)
msg.payload = "reset";

// Change topic or filters — resets watermark and restarts immediately
msg.ntfyOptions = {
    topic:       "new-topic,another",
    filterPrio:  "4,5",
    filterTags:  "warning"
};

Status

| Colour | Shape | Meaning | |---|---|---| | Green | Ring | Polling, no new messages since last check | | Green | Dot | New message(s) received (shows count) | | Red | Dot | Poll error or auth failure | | Grey | Ring | Stopped |

Action buttons

ntfy supports up to 3 action buttons on a notification. Pass them as a string in ntfy's pipe-delimited format, or set msg.ntfyOptions.actions to a JSON array.

String format (node editor or Mustache):

view, Open dashboard, https://dashboard.example.com

Multiple actions (semicolon-separated):

view, Open, https://example.com; http, Restart, https://api.example.com/restart, method=POST

JSON array (via msg.ntfyOptions):

msg.ntfyOptions = {
    actions: [
        { action: "view", label: "Open dashboard", url: "https://example.com" },
        { action: "http", label: "Restart", url: "https://api.example.com/restart",
          method: "POST", clear: true }
    ]
};

Examples

Simple alert

[Inject] → [ntfy-send: topic=alerts, title=Test]

Set msg.payload = "Hello from Node-RED" to send a notification to the alerts topic.

Dynamic topic from message

Set the Topic field to {{payload.topic}} and send:

msg.payload = { topic: "user-sam", body: "Your report is ready" };
msg.ntfyOptions = { message: msg.payload.body };

Priority alert on error

[loki-watch: errors] → [Function: set priority] → [ntfy-send]

// Function node
msg.ntfyOptions = {
    topic:    "home-alerts",
    title:    "Container error detected",
    priority: 5,
    tags:     ["warning"],
    message:  msg.payload
};
return msg;

Watch a topic and route by priority

[ntfy-watch: topic=alerts] → [Switch: msg.ntfyPriority >= 4] → [email node]

Watch and forward to email

[ntfy-watch: topic=alerts] → [Function] → [email node]

// Function node
msg.topic   = msg.ntfyTitle || "ntfy notification";
msg.payload = `${msg.ntfyTitle}\n\n${msg.payload}`;
return msg;

Change topic at runtime

[Inject] → [Function] → [ntfy-watch]

// Switch the subscription to a new topic
msg.ntfyOptions = { topic: "production-alerts" };
return msg;

Self-hosted ntfy with Docker

services:
  ntfy:
    image: binwiederhier/ntfy
    container_name: ntfy
    command: serve
    restart: unless-stopped
    volumes:
      - /mnt/user/appdata/ntfy/cache:/var/cache/ntfy
      - /mnt/user/appdata/ntfy/config:/etc/ntfy
    ports:
      - "80:80"

The Node-RED ntfy-config server URL for this setup would be http://ntfy:80 assuming both containers share a Docker network.

Known limitations

• File attachments (uploading a local file as binary) are not supported in ntfy-send. Use the Attach URL field to attach files from a URL instead.
• Scheduled message delivery (delay) is supported for publishing but ntfy-watch will not receive scheduled messages until they are actually delivered by the ntfy server at the scheduled time.

License

MIT — see LICENSE file.

This package was generated by Claude (Anthropic) and is not actively maintained. Use in production at your own risk.