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 MQTT connection

1. Go to Admin → Settings → MQTT
2. Enter your broker details:
   • Host — broker hostname or IP
   • Port — typically 1883 (plain) or 8883 (TLS)
   • Username / Password — if your broker requires auth
   • Client ID — optional, defaults to apimeld
   • QoS — Quality of Service level (0, 1, or 2 — default: 1)
3. Click Test Connection
4. Save

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

Setting up an MQTT trigger on a task

1. Open a task and go to the Triggers tab
2. Enable MQTT trigger
3. Enter the topic to subscribe to (e.g. sensors/temperature, devices/+/alert)
4. Optionally override the QoS level for this specific task
5. Save

MQTT wildcards are supported:

• + — 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

The MQTT message payload is available as $payload (PowerShell) or payload (JavaScript/TypeScript/Python).

PowerShell:

$logger.Info("MQTT message received")

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

    if ($temp -gt 80) {
        $logger.Warn("Temperature threshold exceeded: $temp°C")
        # call an alert API, send a notification, etc.
    }
}

JavaScript:

logger.info('MQTT message received')

if (payload) {
  const data = JSON.parse(payload)
  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 })
    })
  }
}

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.

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.