MQTT

Publish messages to MQTT topics.

Overview

MQTT publishes messages to topics on an MQTT broker. For each input item, it publishes either the full item JSON (when sendInputData is true) or a custom message string to the specified topic. Supports QoS levels 0 (at most once), 1 (at least once), and 2 (exactly once), as well as the MQTT retain flag. Connects per execution using the mqtt npm package. Supports MQTT, MQTTS (TLS), and WebSocket transports. Input items are passed through unchanged after publishing.

Category: Communication
Tool Name: mqtt
Version: 1

Appearance: Icon: lucide-Radio | Color: #660066

Node Type

Action — processes input items and produces output

Input / Output

Direction	Port(s)
Input	Input
Output	Output, Error

Credentials

This tool requires MQTT credentials. See the Credentials Guide for setup instructions.

Parameters

Parameter	Type	Required	Default	Description
Topic	string	Yes	—	The MQTT topic to publish the message to. Supports expressions like {{ $json.deviceId }}.
Send Input Data	boolean	No	true	Whether to send the input item data as JSON for the message body. When enabled, the entire input item JSON is serialized and published.
Message	string	Yes	—	The custom message string to publish. Only used when “Send Input Data” is disabled. Supports expressions. (shown when Send Input Data is false)
Options	collection	No	{}	Additional publish options.
— QoS	options	No	0	Quality of Service level. 0 = at most once (fire and forget), 1 = at least once (acknowledged delivery), 2 = exactly once (assured delivery).
				Options: 0 (Received at Most Once), 1 (Received at Least Once), 2 (Exactly Once)
— Retain	boolean	No	false	Whether to set the MQTT retain flag. When set, the broker keeps the last retained message on this topic for new subscribers.
Max Concurrency	number	No	10	Maximum number of items to process concurrently.

Output Data

This node does not fan out and does not add any fields. Each input item is published to the broker and then passed straight through to Output — the item JSON is unchanged and binary data is forwarded, so downstream nodes see exactly what arrived.

Because nothing is added, use the presence of an item on Output as the signal that its publish succeeded; a publish that failed becomes an item error instead.

Usage Examples

• Publish sensor data to an MQTT topic
• Send a custom alert message to an MQTT broker
• Push IoT device commands via MQTT with QoS 2 guaranteed delivery
• Broadcast JSON payloads to MQTT subscribers

Example Configuration

Basic usage — publish the whole input item as JSON:

{
  "type": "mqtt",
  "parameters": {
    "topic": "sensors/temperature",
    "sendInputData": true
  }
}

Custom message with acknowledged delivery and retention:

{
  "type": "mqtt",
  "parameters": {
    "topic": "alerts/critical",
    "sendInputData": false,
    "message": "System alert: High temperature detected",
    "options": {
      "qos": 1,
      "retain": true
    }
  }
}

High-reliability configuration — exactly-once delivery:

{
  "type": "mqtt",
  "parameters": {
    "topic": "devices/status/device123",
    "sendInputData": true,
    "maxConcurrency": 5,
    "options": {
      "qos": 2,
      "retain": false
    }
  }
}

Fire-and-forget notification:

{
  "type": "mqtt",
  "parameters": {
    "topic": "notifications/info",
    "sendInputData": false,
    "message": "Process completed successfully",
    "options": {
      "qos": 0,
      "retain": false
    }
  }
}

Sensor data publishing — build the topic per item so one node serves every device:

{
  "type": "mqtt",
  "parameters": {
    "topic": "sensors/{{ $json.deviceId }}",
    "sendInputData": true,
    "options": {
      "qos": 1
    }
  }
}

Alert messages — a custom body instead of the item JSON:

{
  "type": "mqtt",
  "parameters": {
    "topic": "alerts/{{ $json.severity }}",
    "sendInputData": false,
    "message": "Alert: {{ $json.description }}",
    "options": {
      "qos": 1,
      "retain": true
    }
  }
}

Status updates that new subscribers should see immediately:

{
  "type": "mqtt",
  "parameters": {
    "topic": "devices/status",
    "sendInputData": true,
    "options": {
      "qos": 1,
      "retain": true
    }
  }
}

Error Handling

Mode	Behavior
stop	Halts workflow on first error
continue	Skips failed items, passes successful ones through
errorPort	Routes failed items to Error output port

Tips

Publish messages to MQTT broker topics with configurable QoS and retain flag; use when you need to send data to IoT devices or message brokers over MQTT.