Deliveries¶

Delivery is a pre-set configuration for a specific Transport - it controls the configuration and can set values that would otherwise have to be repeated in every notification.

The simplest case though is that you never know or worry about them - if you add an email address as a target for a notification, the email delivery is used, or a phone number for SMS, and if you add a big list of random targets, Supernotify will work out the right delivery for each. See Targets for more information.

If you need, Deliveries can be manually selected on a notification, for example sending some to Telegram and others to email, or having a siren fire also for some. They can also be automatically selected using conditions or Scenarios.

Standard Delivery¶

A Delivery gets configured automatically for every usable transport, it will check the underlying integration, like Ntfy or Telegram, has been set up in Home Assistant, and if it needs entities like Media Players, whether these exist.

For example, if there is an SMTP Integration an email Delivery will be set up, with the SMTP action.

These standard deliveries will default to explicit inclusion (you have to list them in the delivery key of the notification ), with the exception below.

Some transports, email, mobile_push, alexa_devices and sms can reasonably be expected to always notify if configured, and have the ability to pick their targets (an email address is obviously an email address). So the standard delivery for these will be a default inclusion, which means even if a notification has nothing more defined than a message it will be sent out to via these delivery channels. If, however, there are also custom deliveries for these transports, the standard delivery will stand down to explicit, to avoid duplicate notifications.

In any case, the inclusion key can be used, either in the Transport or Delivery configuration, to override any of the automatic choices. See Delivery Inclusion for more on how that works.

Customizing Delivery¶

You may want to create multiple Deliveries for the same channel, for example a plain email and html_email delivery, or different custom notification platforms using the generic transport. Be careful to have constraints, like priority, occupancy or conditions, if there are multiple deliveries so you don't get duplicate notifications.

Or more simply, you can customize the standard delivery created for each transport, here's an example, which refines the standard sms delivery, created because the home already has a working SMS integration, and switches on the delivery only if notification priority is critical or high

If the conditions were more complex than this, a condition block could be applied.

delivery:
    sms: # same name as transport
        priority:
        - critical
        - high

If the name text_message had been chosen here, then there would now be two deliveries, sms ( the automatic standard one ) and text_message (my new custom one) defined.

If you only have one delivery, this is the same thing as:

transports:
    sms:
      delivery_defaults:
        occupancy: only_out
        priority:
        - critical
        - high

Other Reasons to Use Delivery¶

• Make sure critical notifications are heard. Fire up the sirens, push to mobile apps and send off email or SMS
• If you're paying for SMS, keep it only for critical notifications
• Adapt messaging style to occupancy
• Reduce notification noise by using sounds, like dings or bells, on chime devices or voice assistants

There are more examples in the Recipes section.

Simplifying Deliveries¶

• If you only have one delivery config, don't bother with the delivery: config, just update the delivery_defaults for the transport, so the standard delivery is set up the way you like it
• If you have multiple deliveries for the same Transport, then set common defaults at Transport level, using delivery_defaults
• Use Scenarios to apply common chunks of config
• Move to a scenario-only configuration (recommended)
• From v2.10.0 this is a simple change in the Delivery Control settings
• In older versions, it requires a YAML change, setting inclusion to scenario (or explicit, which is also offered in the action editor's Delivery list) for every delivery, or all at once with Delivery Control
• This makes Deliveries more of an opt-in model than opt-out, since all Deliveries are now inactive unless explicitly selected

In this snippet, all Delivery configurations for alexa_devices will use the defined target group.

    alexa_devices:
      delivery_defaults:
        target:
          - group.alexa_announcements

Overriding Message and Title¶

If your downstream transport has specific needs for the message and/or title then these can be overridden or amended for only the deliveries that need them.

delivery:
  custom_notify:
    transport: generic
    action: notify.very_custom
    message: HOME ASSISTANT NOTIFICATION

For this delivery, whatever the message on the notification, it will be replaced by "HOME ASSISTANT NOTIFICATION" when delivered to the custom notification.

For amending rather than overriding, see the Alexa Whisper Recipe for an example of using message_template in a Scenario.

Controlling Targets¶

For fine-grained control over how any targets pre-defined in a delivery are treated, for example when explicit targets provided in a notification action call, Delivery has an optional target_usage key, taking values of:

• no_action - Only uses the Delivery target if there's no target on the notification action call
• no_delivery - Only uses the Delivery target if there's no target applicable to this delivery
• merge_delivery- Combines the targets in the Delivery with any on the action call, only where delivery already has a target
• merge_always - Combines the targets in the Delivery with any on the action call, or if there's no target on the notification, it defaults to the Delivery target
• fixed - Only ever delivers to the targets in the Delivery config, ignoring any direct or indirect (for example person_id) in the action call

Additionally, target_required defines if this delivery needs targets to work, and should be skipped if no targets are resolved as specific to it, for example based on the target_categories option to select by category. This has values:

• always - Targets are mandatory, skip this delivery if no targets identified for it
• never - Don't require targets, and don't even waste time computing them and don't supply them to the transport adaptor
• optional - Don't require targets but still compute them and make them available for the notification

Home Assistant area_id, floor_id and label_id targets are resolved to the entities they reference before anything else looks at them, using the same core logic as a Home Assistant entity action, so groups are expanded and an entity inherits the area of its device. The delivery's target_categories and target_select options then apply to those entities, exactly as they would to an entity named in the notification.

See Targets for more info on how to use them.

Delivery Inclusion¶

A list of inclusion options controls how deliveries are included, each delivery can have multiple options included, though some of them are mutually impossible, like default and explicit

explicit and scenario work the same way when a notification is sent. The difference is in the supernotify.notify action editor, whose Delivery list offers default and explicit deliveries, but not ones only a scenario, or a fallback, should use.

Delivery Control¶

A delivery without its own inclusion takes its transport's, which is default for email, mobile push, notify entities, Alexa Devices and HTML5, and explicit for the rest. To give every delivery the same default instead, go to Settings > Devices & services > Supernotify > Configure > Delivery Control and set Default inclusion. A transport's own delivery_defaults in YAML still override it, as does a delivery's own inclusion.

The same page has Spoken delivery occupancy, a default occupancy for spoken deliveries, such as Alexa and TTS announcements, for example only_in to speak only to people at home. It works the same way, only for deliveries whose transport speaks. Recipients without a Person are never in or out, so only_in and only_out always leave them out - see Users without Person entries. Left as Not controlled, and Each transport's own default for inclusion, nothing changes.

Entities¶

Each delivery has a switch.supernotify_delivery_XXXX entity, on the SuperNotify device, that is the delivery enabled flag, with the delivery configuration as attributes. Turning it off ( by main UI, Developer Tools, automations, API or whatever ) disables the delivery, and turning it on enables it again, for run-time control of notifications. Each transport also has a switch, switch.supernotify_transport_XXXX, which allows all deliveries for that transport to be quickly disabled, without changing the delivery switches themselves. Only a transport that is loaded, and so usable, has a switch, as do only its deliveries. A switch left from a transport or delivery that is no longer loaded shows as unavailable, and can be deleted from its entity settings.

Switching a delivery or transport on or off lasts across restarts and reloads, see Overrides.

Overrides¶

Switching a scenario, recipient, delivery or transport on or off with its switch overrides its configured enabled value. The override lasts across restarts and reloads, while its configured value - its own enabled, or for a delivery without one, its transport's - is unchanged. Changing that value in the configuration, and reloading, puts it back as configured. So does the supernotify.reset_overrides action, for everything or for one kind at a time.

• A scenario without conditions is driven by its Scenario Manual binary_sensor. That on/off state is not an override of the configuration, so supernotify.reset_overrides leaves it as it is, and only puts the scenario's switch back.
• An override belongs to its switch entity. While the switch is disabled in Home Assistant, its override is not applied and the configured value is used, and supernotify.reset_overrides can't clear it. Enabling the switch again brings the override back - turn it back with the switch, or use supernotify.reset_overrides once the switch is enabled again.
• A delivery with no enabled of its own follows its transport's configured enabled, so changing the transport's enabled in the configuration also ends that delivery's override.
• The override is saved by Home Assistant's own restore state mechanism, so it lasts as long as the switch exists: it's forgotten if the switch has been missing for about 7 days, and, as Home Assistant saves it every 15 minutes and on a clean shutdown, a change up to 15 minutes before a crash can be lost.

Removing¶

Its also possible to completely switch off transports, so that they don't show up anywhere in Home Assistant, and there's no Delivery option, and no ability to dynamically switch them back on.

transports:
  mobile_push:
    load: false

Extreme Example¶

Its unlikely any Delivery would ever look quite like this, with every configuration key used. The full choice can also be found in the Delivery Schema definition.

delivery:
    all_bells_and_whistles:
        # Alias does nothing, just a place for longer name
        alias: Make a fuss if alarm armed or high priority
        # Which of the built-in transports to use
        transport: generic
        # This defaults to true, quick way to switch off this delivery
        enabled: true
        # Which Home Assistant action (aka 'service') should be called
        action: script.my_alerter
        # These are fine-tuning options for the transport
        options:
            # only pass `entity_id` targets to the delivery
            target_categories:
              - entity_id
            # narrow down the entity ids selected
            target_include_re:
              - media_player\.chime_[A-Za-z0-9_]+
              - mqtt\.siren_[A-Za-z0-9_]+
            # don't deliver to a target already notified in this action
            unique_targets: true
        # bunch of data that only makes sense to the transport
        data:
            noise_level: scarey
            jitter: 23
        # standard targets to use
        target:
            entity_id:
                switch.hall_light
                switch.garage_buzzer
            person_id:
                person.joe_bob
        # use these targets always, whether or not the notification has explicit targets
        target_usage: merge_always
        # if there's no targets don't notify ( which always happen anyway because of the merge targets above )
        target_required: optional
        # Use this delivery only when explicitly selected by a scenario, or if all other deliveries fail with at least one error
        inclusion:
          - scenario
          - fallback_on_error
        # only deliver if notification is high or critical
        priority:
            - high
            - critical
        # only deliver if there's someone determined ( by mobile app tracker ) to be home
        occupancy: any_in
        # apply a further time and day of week condition
        conditions:
              alias: "Time 15~02"
              condition: time
              after: "15:00:00"
              before: "02:00:00"
              weekday:
                - mon
                - wed
                - fri
        # Send this delivery last ( this has affect on unique selection choice, so another delivery might hit a target first)
        selection_rank: last
        # fix the message and title, ignoring what's sent on notification
        message: ALERT!
        title: Overridden title