---
title: MQTT event handler
description: The MQTT event handler allows you to send Kapacitor alert messages to an MQTT handler. This page includes configuration options and usage examples.
url: https://docs.influxdata.com/kapacitor/v1/reference/event_handlers/mqtt/
estimated_tokens: 4165
product: Kapacitor
version: v1
---

# MQTT event handler

[MQTT](http://mqtt.org/) is a lightweight messaging protocol for small sensors and mobile devices. Kapacitor can be configured to send alert messages to an MQTT broker.

## Configuration

Configuration as well as default [option](#options) values for the MQTT event handler are set in your `kapacitor.conf`. Below is an example configuration:

```toml
[[mqtt]]
  enabled = true
  name = "localhost"
  default = true
  url = "tcp://localhost:1883"
  ssl-ca = "/etc/kapacitor/ca.pem"
  ssl-cert = "/etc/kapacitor/cert.pem"
  ssl-key = "/etc/kapacitor/key.pem"
  client-id = "xxxx"
  username = "xxxx"
  password = "xxxx"
```

> Multiple MQTT brokers may be configured by repeating `[[mqtt]]` sections. The `name` acts as a unique identifier for each configured MQTT client.

#### `enabled`

Set to `true` to enable the MQTT event handler.

#### `name`

Unique name for this broker configuration.

#### `default`

When using multiple MQTT configurations, sets the current configuration as the default.

#### `url`

URL of the MQTT broker. Possible protocols include:

**tcp** - Raw TCP network connection  
**ssl** - TLS protected TCP network connection  
**ws** - Websocket network connection

#### `ssl-ca`

Absolute path to certificate authority (CA) file. *A CA can be provided without a key/certificate pair.*

#### `ssl-cert`

Absolute path to pem encoded certificate file.

#### `ssl-key`

Absolute path to pem encoded key file.

#### `client-id`

Unique ID for this MQTT client. If empty, the value of `name` is used.

#### `username`

MQTT username.

#### `password`

MQTT password.

## Options

The following MQTT event handler options can be set in a [handler file](/kapacitor/v1/reference/event_handlers/#create-a-topic-handler-with-a-handler-file) or when using `.mqtt()` in a TICKscript.

| Name | Type | Description |
| --- | --- | --- |
| broker-name | string | The name of the configured MQTT broker to use when publishing the alert. If empty defaults to the configured default broker. |
| topic | string | The MQTT topic to which alerts will be dispatched |
| qos | int64 | The QoS that will be used to deliver the alerts. Valid values include:0 : At most once delivery1 : At least once delivery2 : Exactly once delivery |
| retained | bool | Indicates whether this alert should be delivered to clients that were not connected to the broker at the time of the alert. |

### Example: handler file

```yaml
id: handler-id
topic: topic-name
kind: mqtt
options:
  broker-name: 'name'
  topic: 'topic-name'
  qos: 1
  retained: true
```

### Example: TICKscript

```js
|alert()
  // ...
  .mqtt('topic-name')
    .brokerName('name')
    .qos(1)
    .retained(TRUE)
```

## Using the MQTT event handler

The MQTT event handler can be used in both TICKscripts and handler files to send alerts to an MQTT broker.

The examples below use the following MQTT broker configurations defined in the `kapacitor.conf`:

***MQTT settings in kapacitor.conf***

```toml
[[mqtt]]
  enabled = true
  name = "localhost"
  default = true
  url = "tcp://localhost:1883"

[[mqtt]]
  enabled = true
  name = "alerts-broker"
  default = false
  url = "ssl://123.45.67.89:1883"
  ssl-ca = "/etc/kapacitor/ca.pem"
  ssl-cert = "/etc/kapacitor/cert.pem"
  ssl-key = "/etc/kapacitor/key.pem"
  client-id = "alerts-broker"
  username = "myuser"
  password = "mysupersecretpassw0rd"
```

### Send alerts to an MQTT broker from a TICKscript

The following TICKscript uses the `.mqtt()` event handler to send alerts to the `alerts` MQTT topic of the default MQTT broker defined in the `kapacitor.confi` whenever idle CPU usage drops below 10%.

***log-cpu-alert.tick***

```js
stream
  |from()
    .measurement('cpu')
  |alert()
    .crit(lambda: "usage_idle" < 10)
    .message('{{ .Time }}: CPU usage over 90%')
    .mqtt('alerts')
      .qos(2)
```

### Send alerts to an MQTT broker from a defined handler

The following setup sends an alert to the `cpu` topic. An MQTT handler is added that subscribes to the `cpu` topic and sends messages to `alerts` MQTT topic of the `alerts-broker` whenever a new message is published.

Create a TICKscript that publishes alert messages to a topic. The TICKscript below sends an alert message to the `cpu` topic any time idle CPU usage drops below 10%.

***cpu\_alert.tick***

```js
stream
  |from()
    .measurement('cpu')
  |alert()
    .crit(lambda: "usage_idle" < 10)
    .message('{{ .Time }}: CPU usage over 90%')
    .topic('cpu')
```

Add and enable the TICKscript:

```bash
kapacitor define cpu_alert -tick cpu_alert.tick
kapacitor enable cpu_alert
```

Create a handler file that subscribes to the `cpu` topic and uses the MQTT event handler to send alerts to the `alerts-broker`.

***log\_cpu\_handler.yaml***

```yaml
id: log-cpu-alert
topic: cpu
kind: mqtt
options:
  broker-name: 'alerts-broker'
  topic: 'alerts'
  qos: 2
  retained: true
```

Add the handler:

```bash
kapacitor define-topic-handler log_cpu_handler.yaml
```