MQTT message received

The MQTT message received trigger fires when a message arrives on an MQTT topic. Use it to react to devices or services that publish messages over MQTT, such as a sensor that reports a value or a button that sends a message when pressed.

You can react to every message on a topic, or only to messages with a specific payload.

Using this trigger from the user interface

If you prefer building automations visually, Home Assistant walks you through this trigger step by step. You pick what to watch, tweak a few options, and save. No YAML knowledge required.

To use this trigger in an automation:

1. Go to Settings > Automations & scenes.
2. Open an existing automation, or select Create automation > Create new automation.
3. In the When section, select Add trigger.
4. Search for and select MQTT message received.
5. In Topic, enter the MQTT topic to listen to.
6. Optional: In Payload, enter the payload the message must have. Leave it empty to trigger on every message on the topic.
7. Select Save.

Options in the UI

Using this trigger in YAML

If you work directly in YAML, or you want to know exactly what Home Assistant does under the hood, this section has the technical reference. It lists the field names you use in YAML, their types, and which ones are required.

In YAML, use trigger: mqtt. A basic example looks like this:

trigger: mqtt
topic: "living_room/switch/ac"
payload: "on"

This runs when the message on is received on the living_room/switch/ac topic.

If the message is JSON, use value_template to pick the part you want to compare with payload. The trigger below only fires when the message on living_room/switch/ac is valid JSON with a state key that has the value on.

trigger: mqtt
topic: "living_room/switch/ac"
payload: "on"
value_template: "{{ value_json.state }}"

You can use limited templates in topic and payload, for example with trigger variables.

trigger_variables:
  room: "living_room"
  node: "ac"
  value: "on"
triggers:
  - trigger: mqtt
    topic: "{{ room ~ '/switch/' ~ node }}"
    payload: "{{ 'state:' ~ value }}"

Options in YAML

Good to know

• This trigger needs the MQTT integration to be set up and connected to your MQTT broker.
• The templates in topic and payload are evaluated only when the trigger is set up. They are not re-evaluated for every incoming message.
• value_template is evaluated for every incoming message on the topic.
• The UI shows Topic and Payload. To use value_template, encoding, or qos, edit the trigger in YAML.

Try it yourself

For this trigger, there is no target entity to change. To test it, publish a message to the topic. You can do this from the MQTT integration: go to Settings > Devices & services, select MQTT, and select Configure next to your broker. Under Publish a packet, enter the topic and payload, and select Publish.

Still stuck?

The Home Assistant community is quick to help: join Discord for real-time chat, post on the community forum with the trigger you’re using and what you expected to happen, or share on our subreddit /r/homeassistant.

Related triggers

Explore related triggers:

• Manual event received: Triggers when an event is fired on the Home Assistant event bus.

• State: Triggers when the state or an attribute changes.