<!-- BusyBot node reference — https://busybot.net/tools/mqtt/ -->

> Node: MQTT (`mqtt`) · Action · v1
> Category: Communication · Credentials: MQTT (`mqttApi`)
> Updated: 2026-08-16

# 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](https://busybot.net/credentials/mqtt-api/) 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:

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

Custom message with acknowledged delivery and retention:

```json
{
  "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:

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

Fire-and-forget notification:

```json
{
  "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:

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

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

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

```json
{
  "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.