1. From the **Integration** list, select **MQTT**.
1. Enter your broker URL in the **Broker URL** field. Supports `tcp`, `ssl`, `mqtt`, `mqtts`, `ws`, `wss` schemes. For example: `tcp://127.0.0.1:1883`.
1. Enter the MQTT topic name in the **Topic** field.
1. In **Optional MQTT settings**, specify additional settings for the MQTT integration if needed.
1. Click **Test** to check that your integration works.
For more details on contact points, including how to test them and enable notifications, refer to [Configure contact points](ref:configure-contact-points).
A test alert notification should be sent to the MQTT broker.
| Topic | The topic to which the message will be sent. |
The integration sends data in JSON format by default. You can change that using **Message format** field in the **Optional MQTT settings** section. There are two supported formats:
### Optional Settings
- **JSON**: Sends the alert notification in JSON format.
- **Text**: Sends the rendered alert notification message in plain text format.
| Message format | If set to `json` (default), the notification message uses the [default JSON payload](#default-json-payload). <br/> If set to `text`, the notification message is fully customizable. |
| Message | Depends on the **Message format** option. <br/> In `json` format, defines only the `message` field of the [default JSON payload](#default-json-payload). <br/> In `text` format, defines the [entire custom payload](#custom-payload). <br/> This field supports [notification templates](ref:notification-templates). |
| Client ID | The client ID to use when connecting to the MQTT broker. If blank, a random client ID is used. |
| Username | The username to use when connecting to the MQTT broker. |
| Password | The password to use when connecting to the MQTT broker. |
| QoS | The quality of service to use when sending the message. Options are `At most once`, `At least once`, and `Exactly once`. |
| Retain | If set to true, the message will be retained by the broker. |
| TLS | TLS configuration options, including CA certificate, client certificate, and client key, and disable certificate verification. |
| Disable resolved message | Enable this option to prevent notifications when an alert resolves. |
## MQTT JSON payload
## Default JSON payload
If the JSON message format is selected in **Optional MQTT settings**, the payload is sent in the following structure.
If the **Message format** option is `json` (the default), the payload is like this example.
```json
{
@ -116,43 +144,42 @@ If the JSON message format is selected in **Optional MQTT settings**, the payloa
}
```
### Payload fields
Each notification payload contains the following fields.
| `receiver` | string | Name of the contact point |
| `status` | string | Current status of the alert, `firing` or `resolved` |
| `orgId` | number | ID of the organization related to the payload |
| `alerts` | array of [alerts](#alert-object) | Alerts that are triggering |
| `groupLabels` | object | Labels that are used for grouping, map of string keys to string values |
| `commonLabels` | object | Labels that all alarms have in common, map of string keys to string values |
| `commonAnnotations` | object | Annotations that all alarms have in common, map of string keys to string values |
| `externalURL` | string | External URL to the Grafana instance sending this webhook |
| `version` | string | Version of the payload |
| `groupKey` | string | Key that is used for grouping |
| `message` | string | Custom message configured in **Message** (**Optional Settings**). <br/> Supports [notification templates](ref:notification-templates); the output is formatted as a string. |
{{<admonitiontype="note">}}
Alert rules are not coupled to dashboards anymore. The fields related to dashboards `dashboardId` and `panelId` have been removed.
When using the `json`**Message format**, only the **message** field of the JSON payload is customizable, and its output is formatted as a string.
To customize the full payload in text or JSON format, use the `text` format and define a [custom payload](#custom-payload).
{{</admonition>}}
### Alert object
The Alert object represents an alert included in the notification group, as provided by the [`alerts` field](#body).
When you set the **Message format** option to `text`, you can customize the entire payload of the MQTT message.
In this mode, the **Message** option defines the entire payload. It supports [notification templates](ref:notification-templates) and can generate notification messages in plain text, JSON, or any custom format.
For examples of templates that produce plain text or JSON messages, refer to [notification template examples](ref:notification-template-examples).
grafana-delivery-bot[bot]
2 weeks ago
committed by