Sending Notifications¶

Use the supernotify.notify action for the easiest way to send notifications, with guidance for each main part of the data section and selectors.

  - 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.)

All of the examples below will work equally with supernotify.notify (easier to use when using in the Actions or Automations UI) or the notify platform compatible notify.supernotify style action.

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, telegram account or similar, or something indirect like a person. See e-Mail for more on configuring e-mail notifications, and Targets for more in general about how to use them.

  - 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.

Its also possible to put the e-mail, mobile action, notify entity or similar directly into the target:

  - action: supernotify.notify
    data:
        message: Something went off in the basement
        target: john@mcdoe.co.bn

Both these examples had a single target. The target field will work with a single value, a list of values, or a defined dictionary of values. Generally the dictionary isn't needed since Supernotify can take a big list and work out what belongs to which notification transport, though you may need it if doing custom notifications to Discord, Telegram or similar.

Complex Targets¶

This is what a complicated target looks like - any of the separate address types can be a string or a list, whatever is most convenient

- action: supernotify.notify
  data:
      message: Something went off in the basement
      target:
          email: john@mcdoe.co.bn
          phone_number: +4398708123987
          telegram: "@bill"
          mobile_app_id:
            - mobile_app.john_phone
            - mobile_app.john_ipad

Category-Prefixed Targets¶

For a target with no address type Supernotify can auto-detect (e.g. an MQTT topic or a Discord channel ID), a plain flat list of targets can tag an entry with its category name and a colon, instead of switching to the dictionary form above:

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

See Targets for the full list of category names and the other ways to qualify a target (a mapping, or setting it directly on a delivery).

Area, Floor and Label Targets¶

Home Assistant's standard target selectors can be used as well as addresses and entities, so a notification can go to "whatever is in the kitchen" or "everything labelled chime", using the same area_id, floor_id and label_id keys as any other Home Assistant action:

  - action: supernotify.notify
    data:
        message: Dinner is ready
        target:
            area_id: kitchen
            floor_id: ground_floor
            label_id:
              - chime

Supernotify resolves them to entities itself, using the same core logic as Home Assistant actions, and then applies each delivery's usual target selection to those entities. An entity in more than one of them - in the kitchen, on the ground floor and labelled chime - is kept just once, and a transport never sees a selector. Unknown areas, floors or labels are logged as a warning rather than silently resolving to nothing.

An action that genuinely knows about areas itself, rather than about the entities in them, takes the area_id in its own extra_data rather than as a target.

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
• 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 and email are selected as deliveries, even if they are not default ones. In addition any deliveries selected by conditions or scenarios will be added to the list.

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

In this case email will be chosen even if the delivery condition or priority is not met, or the delivery is explicit or scenario only, and other deliveries will be switched off. You get just the fixed list you asked for:

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

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, in both supernotify.notify and notify.supernotify.

!!! 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
  action:
  - action: notify.supernotify
    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:

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:
  - data:
      title: 'ALERT: UPS Overloaded'
      message: UPS is overloaded, output voltage {{states('sensor.cyberpower_output_voltage')}}
      data:
        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 effects the delivery called `email`
              data:
                message: Garden sensor was triggered
            sms: # refers to a transport, so effects 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

Alternate Notification Action¶

Supernotify also has compatibility with the original "legacy" notification platform, and the newer Notify Entity style - these are good for compatibility, but both are much more limited in the UI, and for entities, in what can be passed down to fine tune the notification. Use notify.supernotify for the legacy notification style, presuming you've named the platform that way when setting it up.

References¶

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