MQTT message received

The MQTT message received trigger fires an automation when Home Assistant receives a message on a specific MQTT topic. Use it when a device or service publishes MQTT messages that you want to use in an automation, and the device is not already represented by an entity.

Prerequisites

The MQTT integration must be set up and connected to your MQTT broker.

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. Optional: Select Payload and enter the payload that must match before the trigger fires.
6. In Topic, enter the MQTT topic to listen to.
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

• If you do not set Payload (payload), the trigger fires for any message on the configured topic.
• The topic and payload options support limited templates. These templates are evaluated when the trigger is set up. They are not re-evaluated for each incoming MQTT message.
• By default, MQTT payloads are decoded as utf-8. If the payload is binary data, such as an image or another byte payload, set encoding to an empty string in YAML.
• If the incoming payload contains valid JSON, the trigger data includes trigger.payload_json.

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.

More examples

Real scenarios where this trigger fires in automations and scripts. Copy any example and adapt it to your setup.

Automation: toggle a light from an MQTT button

If a button or remote publishes an MQTT message when you press it, this automation toggles a light when Home Assistant receives the matching payload.

• Trigger: MQTT message received
  • Topic: living_room/switch/action
  • Payload: single
• Action: Toggle light

alias: "Toggle the living room light from an MQTT button"
triggers:
  - trigger: mqtt
    topic: "living_room/switch/action"
    payload: "single"
actions:
  - action: light.toggle
    target:
      entity_id: light.living_room

Automation: send a notification from a JSON MQTT message

If a device publishes JSON data, this automation uses a value template to read the action field before checking the payload. Set up this example in YAML because value_template is a YAML option.

• Trigger: MQTT message received
  • Topic: living_room/remote
  • Payload: single
• Action: Send a notification message
  • Target: My Device (notify.my_device)

alias: "Notify when the living room remote sends a single press"
triggers:
  - trigger: mqtt
    topic: "living_room/remote"
    value_template: "{{ value_json.action }}"
    payload: "single"
actions:
  - action: notify.send_message
    target:
      entity_id: notify.my_device
    data:
      message: "The living room remote sent a single press."

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 changed: Triggers when the state or an attribute changes.