MQTT Trigger

Description

The MqttTrigger module is a trigger that initiates a workflow when a message is received on a configured MQTT topic. It connects to an MQTT broker using credentials and subscribes to the specified topic. It supports wildcards: + for a single level and # for multiple levels. The module automatically attempts to parse the message as JSON; if it is not valid JSON, it passes it as a string. It provides both the parsed message and the raw message to the next node, along with trigger metadata (topic, QoS, timestamp).

Configuration

Parameters

Parameter	Type	Required	Description
credentials_id	credentials	Yes	MQTT broker credentials (broker_url, username, password).
topic	text	Yes	MQTT topic to subscribe to. Wildcards: + (single level), # (multi level). E.g.: sensors/+/temperature, devices/#
qos	select	No	Quality of Service: 0 (at most once), 1 (at least once), 2 (exactly once). Default: 0.
trigger_id	hidden	No	Registered trigger ID. Automatically generated.

Credentials

A credential with the following fields is required:

• broker_url: MQTT broker URL (e.g.: mqtt://broker.example.com:1883 or mqtts://... for SSL).
• username: Username for broker authentication.
• password: Password for broker authentication.

Output

{
  "nextModule": "siguiente_modulo",
  "data": {
    "topic": "sensores/sala/temperatura",
    "message": { "valor": 22.5, "unidad": "celsius" },
    "raw": "{\"valor\":22.5,\"unidad\":\"celsius\"}",
    "_trigger": {
      "type": "mqtt",
      "topic": "sensores/sala/temperatura",
      "qos": 0,
      "timestamp": "2026-03-23T10:00:00.000Z"
    }
  }
}

Usage Example

Basic case

{
  "label": "MQTT Trigger",
  "credentials_id": "credencial_mqtt_broker",
  "topic": "sensores/+/temperatura",
  "qos": 0
}

Notes

• The message is automatically parsed as JSON. If parsing fails, it is kept as a string.
• Supports messages in Buffer format, which are converted to UTF-8 strings.
• MQTT wildcards are: + (replaces one topic level) and # (replaces multiple levels, only at the end).
• QoS 0: no delivery guarantee. QoS 1: at least one delivery. QoS 2: exactly one delivery.
• The raw field always contains the original message as a string, regardless of parsing.

Related Nodes

• RedisTrigger (similar trigger for Redis Pub/Sub)
• Webhook (HTTP request trigger)
• decision (to evaluate message content)