MQTT Triggers

Tasks can be triggered by messages published to an MQTT topic. This is useful for IoT devices, event-driven pipelines, and systems that already use MQTT as a message bus.

Prerequisites

ApiMeld connects to an external MQTT broker — it does not include a built-in broker. You need:

• An MQTT broker (Mosquitto, EMQX, HiveMQ, or a cloud service like AWS IoT, Azure IoT Hub)
• The broker's host, port, and credentials

Configuring the broker connection

Go to Admin → Settings → MQTT. The broker status (Connected / Connecting… / Disconnected / Not Configured) is shown at the top of the page and updates in real time.

Connection fields

Field	Description
Broker Host	Hostname or IP address of your MQTT broker (required)
Port	Default: 1883 (plain), 8883 (TLS)
Use custom Client ID	Toggle off to use an auto-generated ID (taskscheduler-<uuid>) — recommended unless your broker requires a fixed ID. A fixed ID causes conflicts if two app instances connect simultaneously.
Client ID	Shown when the toggle above is on. Must be unique across all clients on the broker.
Username	Optional — if your broker requires authentication
Password	Optional — if your broker requires authentication. Saved encrypted; enter a new value to rotate it.
Default QoS	Quality of Service level applied to all subscriptions unless overridden per task (see below)
Keep-Alive (seconds)	Ping interval to keep the connection alive. Default: 60.
Use TLS/SSL	Enable for encrypted connections — required when connecting on port 8883
Skip certificate validation	Only available when TLS is on. Use for self-signed certificates on internal brokers.
MQTT 5	Enable MQTT 5.0 protocol. Default is MQTT 3.1.1.

Testing and saving

Click Test Connection to verify the broker is reachable with the supplied credentials. The Save button is only enabled after a successful test.

ApiMeld maintains a persistent connection to the broker and resubscribes automatically on reconnect.

QoS levels

Level	Description
0	At most once — fire and forget, no delivery guarantee
1	At least once — guaranteed delivery, possible duplicates
2	Exactly once — guaranteed, no duplicates (highest overhead)

For most task triggers, QoS 1 is the right balance. Use QoS 2 only if duplicate executions would cause problems.

Setting up an MQTT trigger on a task

Open a task — the Trigger card is in the right column of the edit form. Select MQTT as the trigger type to reveal these fields:

Field	Description
Topic	The MQTT topic to subscribe to (required). Supports + and # wildcards — e.g. sensors/factory1/temperature or devices/+/alert.
Payload Filter (optional)	Regex or plain string. If set, incoming messages whose payload does not match are silently ignored and do not fire the task.
Debounce (seconds)	Minimum gap between task fires. If messages arrive faster than this, only the first triggers the task and the rest are dropped until the debounce window expires. Leave blank for no debounce.
QoS Override	Overrides the Default QoS set in Admin → Settings → MQTT for this topic specifically. Leave blank to use the broker default.

MQTT wildcards:

• + — single-level wildcard (e.g. devices/+/alert matches devices/sensor1/alert)
• # — multi-level wildcard (e.g. devices/# matches everything under devices/)

Accessing the payload in scripts

When an MQTT message triggers a task, ApiMeld injects the topic, payload, and timestamp as separate variables.

Language	Topic	Payload	Timestamp
PowerShell	$mqttTopic	$mqttPayload	$mqttTimestamp
JavaScript / TypeScript	mqttTopic	mqttPayload	mqttTimestamp
Python	mqtt_topic	mqtt_payload	mqtt_timestamp
Bash	$MQTT_TOPIC	$MQTT_PAYLOAD	$MQTT_TIMESTAMP
C#	MqttTopic	MqttPayload	MqttTimestamp

The payload is a raw string. Parse it as JSON if your device publishes JSON.

PowerShell:

$logger.Info("MQTT message on topic: $mqttTopic")

if ($mqttPayload) {
    $data = $mqttPayload | ConvertFrom-Json
    $temp = $data.temperature
    $logger.Info("Temperature: $temp°C")

    if ($temp -gt 80) {
        $logger.Warn("Temperature threshold exceeded: $temp°C")
        $notifications.SendSlack('Ops Channel', "High temp alert: $temp°C on $mqttTopic")
    }
}

JavaScript:

logger.info(`MQTT message on topic: ${mqttTopic}`)

if (mqttPayload) {
  const data = JSON.parse(mqttPayload)
  logger.info(`Temperature: ${data.temperature}°C`)

  if (data.temperature > 80) {
    logger.warn(`Threshold exceeded: ${data.temperature}°C`)
    await fetch('https://alerts.example.com/trigger', {
      method: 'POST',
      headers: { ...authHeaders, 'Content-Type': 'application/json' },
      body: JSON.stringify({ alert: 'high-temp', value: data.temperature })
    })
  }
}

Python:

import json

print(f"MQTT message on topic: {mqtt_topic}")

if mqtt_payload:
    data = json.loads(mqtt_payload)
    temp = data['temperature']
    if temp > 80:
        notifications.send_slack('Ops Channel', f"High temp alert: {temp}°C on {mqtt_topic}")

Use cases

• IoT sensors: process readings from temperature, humidity, or pressure sensors
• Device alerts: react to device state changes (door open, motion detected, etc.)
• Pipeline events: trigger downstream tasks when an upstream system publishes a completion event
• Home automation: bridge MQTT events to API calls or database writes

Multiple tasks on the same topic

Multiple tasks can subscribe to the same MQTT topic. All matching tasks are triggered concurrently when a message arrives.