---
id: event--mqtt-publisher
title: "MQTT publisher"
summary: "Publishes every incoming `EventData` record as a message to an MQTT topic. Use it to send events or telemetry to an MQTT broker."
audience: user
keywords: "input, topic, clientid, host, port, username, password, websocketconnection, usemqtt5, useretainflag, qos"
---
# MQTT publisher

Publishes every incoming `EventData` record as a message to an MQTT topic. Use it to send events or telemetry to an MQTT broker.

## Pins

| Pin | Kind | Types | Description |
|---|---|---|---|
| Input | input | `Viaducta.Plugins.Event.Types.EventData` | Record to publish. |

The plugin has no output pin; it ends its branch of the flow.

## Configuration

| Field | Type | Default | Description |
|---|---|---|---|
| `Topic` | string (max 255) | | Required. Topic to publish to. |
| `ClientId` | string | | MQTT client id. Empty: a random id at every start. A fixed id must be unique on the broker: two clients with the same id disconnect each other. |
| `Host` | string | | Required. Broker host name or IP for TCP. With `WebsocketConnection` the full WebSocket URI (for example `ws://broker:8080/mqtt`). |
| `Port` | integer (1-65535) | `1883` | Broker port for TCP. Ignored with `WebsocketConnection`. |
| `Username` | string (max 256) | | User name. Credentials are sent when `Username` is set. |
| `Password` | password (max 256) | | Password. |
| `WebsocketConnection` | boolean | `false` | `true`: connect over WebSocket, `Host` is the URI. |
| `UseMqtt5` | boolean | `false` | `true`: MQTT 5.0, `false`: MQTT 3.1.1. |
| `UseRetainFlag` | boolean | `false` | `true`: messages are published with the Retain flag. |
| `QoS` | dropdown: `0` QoS0 (At most once), `1` QoS1 (At least once), `2` QoS2 (Exactly once) | `0` | Quality of service of published messages. |

## Behaviour

- The connection is opened at flow start. An empty `Host` or `Topic`, an invalid `QoS` or a refused or failed first connect stops the flow with an unrecoverable error. After that, a lost connection is reconnected in the background (after 1 s, doubling up to 30 s) and logged as warnings. The plugin keeps the flow running (KeepAlive) and disconnects when the flow stops.
- For every record a message is published to `Topic` with `QoS`, `UseRetainFlag` and `EventData.Data` as the body (empty when null), and the plugin waits for the publish result.
- With `UseMqtt5` also: `DataContentType` → content type, `ReplyTo` → response topic, `Headers` → user properties. With MQTT 3.1.1 these are not sent.
- While the client is disconnected, or when the publish fails or is refused, the record fails with a recoverable error.

## Notes

- `EventData.Channel` is ignored: the topic is always `Topic`. `Id`, `Source`, `Type`, `Subject` and `Time` are not sent.
- No TLS options for TCP connections; use a `wss://` URI with `WebsocketConnection` for encryption.
- Keep secrets in expression settings, e.g. `"Password": "=Secrets.MqttPassword"`.

## Example

```json
{ "Topic": "plant/line1/status", "Host": "mqtt.local", "Port": 1883, "QoS": 1, "UseMqtt5": true }
```

Timer → Script (builds `EventData` with a UTF-8 JSON `Data`) → **MQTT publisher**