node-red-contrib-ntfy-nodes 1.0.0

Node-RED nodes for publishing and subscribing to ntfy notification topics — AI generated, provided as-is without ongoing maintenance

npm install node-red-contrib-ntfy-nodes

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

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-in node, set the same topic, and wire its output to a debug node

ntfy-config

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

Auth types

ntfy-send

Publish a notification. The message body comes from msg.payload unless overridden.

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

Node editor fields

Runtime override — msg.ntfyOptions

Set msg.ntfyOptions to override any field at runtime. All fields optional.

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
    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

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 (comma-separated in the Actions header):

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]

msg.payload = "Hello from Node-RED" → sends 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;

Subscribe and forward to email

[ntfy-in: topic=alerts] → [email node]

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

Runtime topic switch

[Inject] → [Function] → [ntfy-in]

// 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.
• The ntfy-in node uses the JSON HTTP stream endpoint rather than WebSockets. This is more reliable for long-running Node-RED deployments.
• Scheduled message delivery (delay) is supported for publishing but ntfy-in will not receive scheduled messages unless scheduled=1 is added manually via a custom filter (not currently exposed in the node editor).

License

MIT — see LICENSE file.

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