Notifying

Sending Notifications¶

Use the supernotify.notify action to send notifications. In the Actions and Automations UI, it gives guidance and selectors for each main part of the data section.

  - action: supernotify.notify
    data:
        message: Garden sensor triggered
        priority: high
        delivery: mobile_push

supernotify.notify also retains the original context of the action, and propagates that down to any actions it calls, such as for underlying notification transports or moving a PTZ camera. (See the original Home Assistant blog post for more on tracing context.)

There are lots more examples in the Recipes, including how to make it work well with Frigate, AppDaemon and Alexa.

Simplest Example¶

In this example, there's no configuration, target or anything more than the standard message.

This notification will go out to all the implicit deliveries. If there's no configuration for Supernotify, then the default behaviour is to send a mobile push notification to all the devices for everyone with a Person entry in Home Assistant.

  - action: supernotify.notify
    data:
        message: Something went off in the basement

Adding Targets¶

Targets can be direct addresses, like an email address, phone number or notify entity, or something indirect like a person, area or label.

  - action: supernotify.notify
    data:
        message: Something went off in the basement
        target: person.john_mcdoe

In this case, the notification will go only to John: to any mobile devices he's running Home Assistant on, and to any e-mail addresses that have been configured for him in Supernotify's recipients configuration.

Simple Targeting¶

target can take a single value, or a big mixed list, and Supernotify works out which notification transport each one belongs to. Targets with an obvious format, like an e-mail address, phone number or entity ID, are recognized automatically. Anything else gets a target category prefix, such as topic: for MQTT or discord_channel: for Discord.

  - action: supernotify.notify
    data:
        message: Something went off in the basement
        target:
            - person.john_mcdoe
            - jane@mcdoe.co.bn
            - +4398708123987
            - notify.kitchen_alexa
            - discord_channel:9585
            - topic:security/basement/alert

Home Assistant's area_id, floor_id and label_id targets work too, so a notification can go to "whatever is in the kitchen".

Simple targeting covers most notifications. When you need more precise control, such as giving two e-mail deliveries different addresses, see Precise Targeting. Targets also lists all the target categories.

Notification Priority¶

Use the priority key in data to set an optional priority. This can be used within Supernotify to switch on or off deliveries or scenarios ( for example a siren to accompany 'critical' notifications).

It will also be mapped to delivery priority flags where the underlying transport allows, for example Mobile Push, Gotify, Ntfy, SMTP, Telegram.

Valid Priorities:

• critical
• high
• medium
• low
• minimum

Example Message

  - action: supernotify.notify
    data:
        message: Something boring happened
        priority: low

Duplicate Notifications¶

Notifications are checked for duplicates based on a selected policy. This can also be turned off for individual notifications using force_resend.

  - action: supernotify.notify
    data:
        message: Something happened
        force_resend: true

See Duplicate Configuration for more information.

Controlling Delivery Selection¶

Delivery selection can be passed in the data of an action call using the delivery_selection key, or implied from the shape of the delivery: key itself. It can be set to one of three values:

• implicit - The default
  • All deliveries whose own inclusion includes default are enabled, plus any switched on by an active scenario
  • This is implied if delivery: is a dictionary mapping, or is left out entirely
• explicit - Switch off delivery defaulting
  • Only deliveries listed on the action call are enabled, plus ones switched on by a scenario
  • This is implied automatically if delivery: is given as a list or a single value
• fixed - Switch off delivery defaulting and scenario delivery selection
  • Only the list of deliveries in the action call will be used, even if a scenario condition were to select another one
  • Deliveries with priority or condition filtering will have this overridden - only a disabled delivery/transport stops a fixed selection
  • This is never implied from delivery:'s shape - it must always be set explicitly

An explicit delivery_selection always wins over whatever the shape of delivery: would otherwise imply - it's a default, not an override. If in doubt, add the delivery_selection to make it clear.

  - action: supernotify.notify
    data:
        message: Garden sensor triggered
        delivery:
            mobile_push: # tunes an existing (default or scenario) delivery
                data:
                    clickAction: https://my.home.net/dashboard

In this example, mobile_push is tuned but not selected - the default deliveries, and any switched on by a scenario, go out as normal.

  - action: supernotify.notify
    data:
        message: Garden sensor triggered
        delivery:
            - mobile_push
            - email

In this case only mobile_push and email are selected, even if they're explicit or scenario inclusion only, plus any deliveries switched on by a scenario. Each delivery's own condition and priority still apply.

  - action: supernotify.notify
    data:
        message: Garden sensor triggered
        delivery_selection: fixed
        delivery:
            - email

Here email is chosen even if its condition or priority is not met, and every other delivery is switched off. You get just the fixed list you asked for.

Delivery and Delivery Control¶

In the action editor, supernotify.notify has a Delivery picker of the configured deliveries. When added, it starts with the implicit deliveries used by default, and you can add to or take away from these as needed.

Under Advanced, a free-form Delivery Control (delivery_control) takes anything delivery: would. The two are merged into one delivery: before the notification is made. A delivery in both takes its form from Delivery Control, so it can be picked in the dropdown and tuned in Delivery Control:

  - action: supernotify.notify
    data:
        message: Garden sensor triggered
        delivery:
            - mobile_push
            - email
        delivery_control:
            mobile_push:
                data:
                    clickAction: https://my.home.net/dashboard

Names picked in the dropdown mean "only these", so when Delivery Control holds a mapping, the merged selection is explicit. Delivery Selection (delivery_selection), also under Advanced, changes that. Left out entirely, delivery selection stays implicit, as before.

delivery_control is only for the supernotify.notify action editor. delivery: still takes a name, a list or a mapping directly, as in the examples above.

!!! info Delivery Selection vs Inclusion delivery_selection here is a per-action-call choice of how deliveries get resolved for this one notification. It's a different mechanism from a delivery's own config-time inclusion list (default / scenario / explicit / fallback / fallback_on_error - see Delivery Selection), which decides whether that delivery is a candidate for implicit selection at all. The two happen to share the word "explicit" for unrelated things - delivery_selection: explicit is about the action call; a delivery with inclusion: explicit is excluded from implicit selection, as does any other value other than default (or left unstated, which is equivalent to default). inclusion: explicit works the same as inclusion: scenario when sending, except that explicit deliveries are offered in the action editor's Delivery list, and scenario-only ones aren't.

When Scenarios Disagree¶

Each scenario can set a delivery's enabled to true, false, or leave it empty - see Overriding Delivery Selection and Configuration.

If more than one scenario is active at once and they disagree on the same delivery, false always wins, regardless of how many other active scenarios enabled it - there's no priority or ordering between scenarios.

The only way to override a scenario's false is for the action call itself to explicitly re-enable that delivery in its own delivery: data. This is a deliberate fail-safe default (a scenario that says "don't send this" is never silently overruled by another scenario), but it also means there's currently no way for a scenario author to mark their enabled: true as one that should win a conflict.

Using from an Automation¶

In this example, when an Actionable Notification is sent with action Red Alert, a notification is triggered in Supernotify using the red_alert scenario. In this case, the scenario uses sirens, chimes and Alexa noises to raise a ruckus so there's no need for message or title.

- id: action_red_alert
  alias: Action Red Alert
  initial_state: true
  triggers:
  - trigger: event
    event_type: ios.action_fired
    event_data:
      actionName: Red Alert
  actions:
  - action: supernotify.notify
    data:
      apply_scenario: red_alert

In this example, a mobile notification goes out to notify of the dishwasher finishing, and email is switched off.

- id: '1762520266950'
  alias: Dishwasher Finished
  description: 'Push alert when dishwasher done'
  triggers:
  - trigger: state
    entity_id:
    - sensor.dishwasher_operation_state
    to:
    - finished
  actions:
  - action: supernotify.notify
    data:
      message: Dishwasher is finished
      delivery:
        email:
          enabled: false

Automation and Templates¶

Templates can be used freely, as in other notify integrations.

- id: ups-overloaded
  alias: Send notification when UPS is overloaded
  triggers:
  - entity_id:
    - sensor.cyberpower_status
    to: Overloaded
    trigger: state
    for:
      hours: 0
      minutes: 0
      seconds: 30
  actions:
  - action: supernotify.notify
    data:
      title: 'ALERT: UPS Overloaded'
      message: UPS is overloaded, output voltage {{states('sensor.cyberpower_output_voltage')}}
      priority: high

Adding a Link to Mobile Push Notification¶

  - action: supernotify.notify
    data:
        title: Security Notification
        message: Garden sensor triggered
        delivery:
            mobile_push:
                data:
                    clickAction: https://my.home.net/dashboard

Note here that the clickAction is defined only on the mobile_push delivery. However it is also possible to simply define everything at the top level extra_data section and let the individual transport adaptors pick out the attributes they need. This is helpful either if you don't care about fine tuning delivery configurations, or using existing notification blueprints, such as the popular Frigate Camera Notification Blueprints.

Customizing message per channel¶

  - action: supernotify.notify
    data:
        message: Garden sensor triggered
        title: Something has happened
        delivery:
            email: # only affects the delivery called `email`
                data:
                    message: Garden sensor was triggered
            sms: # refers to a transport, so affects all deliveries based on SMS transport
                data:
                    message: Garden Activity
                    title: HASS

Extra Data¶

The top level extra_data can hold anything that isn't a Supernotify action field, and is offered to every delivery. It is used for two things:

• Values for the underlying integration, passed straight through. If there are multiple integrations, all of them will get this data ( other than where Supernotify knows the integration and that they can't handle extra data items).
• Tuning for Supernotify's own transports, such as chime_tune for the Chime transport. Each transport takes out the keys it recognizes, and passes the rest on to the integration.

  - action: supernotify.notify
    data:
        message: Garden sensor triggered
        title: Something has happened
        delivery: zify
        extra_data:
          zify_back_channel: 1041

Since extra_data goes to every delivery, transport tuning is better defined in the data section of the specific delivery, so it only affects that delivery. This can be done in the delivery configuration, or for a single notification in a delivery override, as in the mobile_push example above.

supernotify:
  delivery:
    xmas_chime:
      transport: chime
      data:
        chime_tune: christmas_05

Compatibility with Notify Platform Actions¶

For compatibility, Supernotify also works as an original "legacy" notify platform, and as a newer Notify Entity. Both are much more limited in the UI, and a Notify Entity is also limited in what can be passed down to fine tune the notification, so use supernotify.notify wherever you can.

The legacy action is notify.supernotify, assuming you've named the platform supernotify when setting it up. It only takes message, title and target at the top level, so everything else from the examples on this page goes in a nested data: section:

  - action: notify.supernotify
    data:
        message: Garden sensor triggered
        target: person.john_mcdoe
        data:
            priority: high
            delivery: mobile_push

References¶

The full range of things that go into the second level data: section is documented at Notify Action Data Schema