Mobile Push Transport Adaptor¶

Discovery¶

Default delivery. If at least one Companion App device is registered (a mobile_app config entry exists) and no mobile_push delivery is configured, a mobile_push delivery is generated automatically and fires on every notification, with targets resolved per-recipient from the HA Companion App at delivery time.

Send a push message out, with option for camera integration, mobile actions, and translate general priority to Apple specific push priority.

Some functionality may also work with Android push, though has not been tested.

Although Supernotify will automatically set most useful mobile push options, its also possible to directly set them, as in this example:

  - action: supernotify.notify
    data:
      message: Movement at garden gate
      priority: high
      media:
        camera_entity_id: camera.porch
        camera_ptz_preset: garden_gate
      action_groups:
        - security_actions
      delivery:
        mobile_push:
          data:
            tag: "backyard-motion-detected"
            presentation_options:
              - alert
              - badge
            push:
              sound:
                name: "US-EN-Alexa-Motion-Detected-Generic.wav"
                volume: 1.0

Critical on Android¶

A critical notification goes to Android phones the way the companion app documents critical notifications: ttl: 0 and priority: high, so a phone saving battery gets it straight away, and the alarm_stream channel, so it sounds even with Do Not Disturb on or the phone on silent - the Android counterpart of iOS's interruption-level: critical.

The companion app's own channel and ttl, when set in the data, are kept as they are, so a critical notification can still use a channel of its own (mobile_push_critical_priority: normal changes the high priority):

  - action: supernotify.notify
    data:
      message: Smoke in the kitchen
      priority: critical
      delivery:
        mobile_push:
          data:
            channel: smoke_alarm

Android Commands and Spoken Text¶

The companion app takes notification commands and TTS as the message of a call of their own, so Supernotify sends them that way, to Android phones only: mobile_push_command_dnd (alarms_only, priority_only, total_silence, off), mobile_push_command_ringer_mode (normal, silent, vibrate) and mobile_push_command_screen_on each go just before the notification, and mobile_push_tts_text 5 seconds after it, so the notification's own sound isn't cut off (mobile_push_tts_delay changes that, 0 for straight away) - for a critical notification on the alarm stream at full volume (alarm_stream_max, the app puts the volume back afterwards), since a watch's alarm volume can be too low to hear:

  - action: supernotify.notify
    data:
      message: Water leak under the sink
      priority: critical
      extra_data:
        mobile_push_command_screen_on: true
        mobile_push_tts_text: Water leak under the sink

Notification Grouping¶

Set mobile_push_group in extra_data: to visually stack notifications together on the device (iOS thread-id / Android notification group):

  - action: supernotify.notify
    data:
      message: Someone is at the front door
      extra_data:
        mobile_push_group: security

If left unset, a notification with media.camera_entity_id is grouped under that camera's entity id automatically; otherwise it's left ungrouped, so it appears on its own rather than being stacked with unrelated notifications. Critical-priority notifications are never grouped - iOS doesn't support it for them.

Tap URL and Live View¶

A notification level action sets what opens when the notification is tapped, for both platforms - it becomes url on iOS and clickAction on Android. A path such as /lovelace/cameras opens in the Companion App, a full URL in the browser.

mobile_push_live_view_entity sets the camera iOS streams live when the notification is expanded, independently of where the image comes from - for example a Frigate snapshot as the image and the camera itself as the live view. Android has no live view, so it's left out there.

  - action: supernotify.notify
    data:
      message: Car on the driveway
      media:
        snapshot_url: https://frigate.local/api/events/1696512345.123-abc/snapshot.jpg
        camera_entity_id: camera.driveway
      actions:
        - level: notification
          uri: /lovelace/cameras

Default Delivery¶

A default Delivery called mobile_push will be automatically generated for Mobile Push transport if no explicit ones created, since this is the new standard HomeAssistant notification provider. If you don't want to use it, then use configuration as below:

transports:
  mobile_push:
    disabled: false

Auto generating targets¶

By default, where no explicit target is given, mobile push will send to all known devices of all known recipients ( usually the list of Person integration entries in Home Assistant, and mobile apps found in Home Assistant that have their user_id and Notify Entities available), and filter those recipients by occupancy status if wanted in the Delivery configuration.

Mobile Push can also do its own device discovery and ignore recipients. If you want to switch off that behaviour, and drive it only by the defined recipients, then switch on device discovery.

transports:
  mobile_push:
    delivery_defaults:
      options:
        device_discovery: true

By default this will look for all mobile_app devices, and can be narrowed down by using the device_model_select,device_manufacturer_select, device_area_select, device_label_select and device_os_select patterns.

transports:
  mobile_push:
    delivery_defaults:
      options:
        device_discovery: true
        device_label_select:
          include:
            - parents
          exclude:
            - kids
        device_manufacturer_select:
          exclude:
            - Apple
            - Amazon
        device_model_select: .*Pixel.*
        device_os_select:
          exclude:
            - MacOS
            - iOS

You can also use the device select options if not using auto-discovery - this will then limit that delivery to matching devices when they have been auto-discovered at start-up for all deliveries, or have been manually defined for recipients.

Explicit Targets¶

To pin a delivery to one specific device, give its mobile_app_id as a bare value - the same form used for a device under recipients (see People) - not the dotted notify.mobile_app_<device> service-call form:

delivery:
  alert_phone:
    transport: mobile_push
    target_usage: fixed
    target:
      - mobile_app_my_phone

notify.mobile_app_my_phone is the Notify Entity action-call form (an entity_id target, used by transports like notify_entity and tts), not a mobile_app_id - mobile_push doesn't consume entity_id targets at all, so a dotted target here resolves to nothing, and the delivery silently falls back to its normal recipient-based target instead of the one device you named. target_usage: fixed is also needed if you don't want that recipient-based fallback - without it, the configured target: is added to the recipient-resolved targets rather than replacing them (see Controlling Targets and Targets).

References¶

Home Assistant Core¶

• Mobile App Integration
• Companion App Notifications
• Open Issues