Send rich push notifications from Home Assistant through the Notify! Partner API to iPhones, browsers, Macs and whole Device Groups, and drive the iOS-only features from your automations: Live Activities, Lock Screen widgets and Home Screen widgets.
Made with love by Pingie.com
The integration adds a notification action for each Notify! target you set up, listed in the automation editor as Send notification using Notify! to My iPhone (with your own device's name), so it cannot be mistaken for the Companion App's own action for the same phone. Every parameter the Notify! API takes is a field of its own: the message, a title, a sender icon, a hero image, a notification thread, and the time sensitive flag that breaks through Focus. Only the message is required.
It also drives the parts of Notify! that are not notifications at all: Live Activities (a single Lock Screen tile that updates in place while something is running), Lock Screen widgets (one named value that stays), Home Screen widgets (the whole Live Activity content set on a tile that stays), and beacons (reverse monitoring that alerts you when something stops happening).
- A notification action per target, named for Notify! and the device, with one field per API parameter
- Notifications to any target: iPhones, browsers registered through the Notify! web app, Macs running the Notify Listener, and Device Groups that mix them
- Rich notifications: title, sender icon, hero image, threading, time sensitive delivery
- Live Activities: start a Lock Screen tile, move it while the job runs, and finish it, with progress bars, staged progress, live countdowns, metric rows and a tappable button
- Lock Screen widgets: put a sensor reading on the Lock Screen and keep it current
- Home Screen widgets: the same content as a Live Activity, on a tile that stays
- Beacons: ping one on a schedule so Notify! tells you when Home Assistant stops running
- UI configuration, with credentials checked against the API before the entry is created and without ringing your phone
- Per-entry defaults for title, icon, image and thread, overridable per automation
- Multiple devices and groups side by side, one notification service each
- Home Assistant 2024.11.0 or newer
- The Notify! app, with a Device ID and token (Settings in the app)
- Live Activities and both kinds of widget additionally need an iPhone (or, for widgets, an iPad). Home Screen widgets need the Notify! app 6.09.03 or newer. See Platform support.
- Beacons need only their ping URL from the app, not a configured device.
- Make sure HACS is installed.
- Go to HACS > Integrations, open the three dot menu and choose Custom repositories.
- Add
https://github.com/simplytoast1/Notify-for-HomeAssistantwith category Integration. - Find Notify! Alerts in HACS and install it.
- Restart Home Assistant.
Copy custom_components/notify_api into your Home Assistant config directory and restart:
config/
└── custom_components/
└── notify_api/
├── __init__.py
├── api.py
├── config_flow.py
├── const.py
├── manifest.json
├── notify.py
├── services.py
├── services.yaml
├── strings.json
└── translations/
└── en.json
- Settings > Devices & Services > Add Integration, then search for Notify! Alerts.
- Enter the Device or Group ID and its token, both from the Notify! app.
- Optionally give it a name. That name becomes the service name, so "My iPhone" gives you
notify.my_iphone. Left blank, the device's own name from the Notify! app is used.
The credentials are checked against GET /link before the entry is created. That resolves the ID and reports the device or group it belongs to, without sending anything to the device. Note that it does not prove notifications are deliverable: a device whose notification permission was revoked still validates. To check that end to end, send one from Developer Tools > Actions.
Press Configure on the integration to set defaults for the title, icon, image and thread, plus whether notifications are time sensitive. Any field an automation leaves out falls back to its default, and any field an automation sets wins. Set the icon once here and every notification carries it.
Add the integration once per device or group. Each gets its own notification service:
- "My iPhone" gives
notify.my_iphone - "Family Group" gives
notify.family_group
Notifications and the iOS-only features have different reach, and it is worth knowing which is which before building an automation around one.
| Notifications | Live Activities | Lock Screen widgets | Home Screen widgets | |
|---|---|---|---|---|
iPhone or iPad (8 character or IO… ID) |
yes | yes | yes | yes |
Browser (WB… ID) |
yes | no | no | no |
Mac running the Notify Listener (MC… or 8 character ID) |
yes | no | no | no |
Device Group (GRP… ID) |
yes, fanned out to every member | no | no | no |
Notifications work everywhere. A browser and a Mac are ordinary devices to the API: the same action reaches them, and nothing in an automation needs to know which kind of screen is on the other end. A group fans out to a mix of all of them.
Live Activities and widgets are iOS features. They only appear in the Notify! app on an iPhone or iPad; whether a particular iPad shows Live Activities is down to iPadOS, so it is not second-guessed here. Calling one against a browser, a Mac or a Device Group is refused with a message saying so, rather than being sent and silently doing nothing. The integration knows what each target is because it records the platform Notify! reports when the target is set up. For an entry saved before 1.2.1 it falls back to the ID prefix, which recognises browsers and newer Macs; saving the entry's settings once records the platform and closes that gap.
Each target you set up gets its own action, listed in the automation editor under Notifications as Send notification using Notify! to name. The name is the one you gave the entry, so an entry called "My iPhone" gives:
- Send notification using Notify! to My iPhone, called as
notify.my_iphone
The Companion App's action for the same phone (notify.mobile_app_my_iphone) sits in the same list, and the Notify! one is the one that says so.
| Field | Required | Description |
|---|---|---|
message |
yes | The notification text, up to 16 KB. The Lock Screen shows a shortened version and the full text is kept in the app's History, which is where tapping the notification takes you. |
title |
no | Heading shown above the message. Left blank, the default title set under Configure is used, or Notify! if there is none. The API has no untitled notifications. |
icon_url |
no | HTTPS URL of the small circular sender icon. If it cannot be loaded the API falls back to a generic icon, so the notification always displays. |
image_url |
no | HTTPS URL of a hero image shown inside the notification when it is expanded. JPEG, PNG or GIF, up to 10 MB. |
group_type |
no | Thread. Notifications sharing a value collapse into one thread on the device; different values create separate threads. It has no effect on addressing: a group notification goes to every member regardless. |
time_sensitive |
no | Lets the notification break through Focus and Do Not Disturb. Reserve it for genuine alerts such as leaks, smoke or security events. Overuse trains people to ignore it. |
icon_url and image_url must be HTTPS; anything else is refused while you edit the automation rather than when it runs. The size limits (16 KB for the message, 2 KB for the title, 1 KB for each URL and the thread) are counted in bytes, as the API counts them, so emoji use them up faster than their length suggests.
Version 1 could only offer message and title as fields, so everything else went in a data mapping. That still works, unchanged, and includes the API's own camelCase spellings (iconUrl, imageUrl, groupType, timeSensitive). A field set on the action wins over the same field in data. data is still listed in the editor, under advanced mode, for automations that use it.
Plain:
action: notify.my_iphone
data:
message: This is a test notificationEverything:
action: notify.my_iphone
data:
title: Security Alert
message: Motion detected at the front door
icon_url: https://icons.getnotifyapp.com/security.png
image_url: https://ha.example.com/local/front_door_snapshot.jpg
group_type: security
time_sensitive: trueDoor sensor:
automation:
- alias: Front door alert
triggers:
- trigger: state
entity_id: binary_sensor.front_door
to: "on"
actions:
- action: notify.my_iphone
data:
title: "🚪 Security"
message: Front door opened
icon_url: https://icons.getnotifyapp.com/door.png
group_type: securityTemperature, with a templated message:
automation:
- alias: High temperature alert
triggers:
- trigger: numeric_state
entity_id: sensor.living_room_temperature
above: 75
actions:
- action: notify.my_iphone
data:
title: "🌡️ Temperature"
message: >-
Living room is {{ states('sensor.living_room_temperature') }}°F
group_type: climateA water leak, loud enough to break through Focus:
automation:
- alias: Water leak
triggers:
- trigger: state
entity_id: binary_sensor.basement_leak
to: "on"
actions:
- action: notify.my_iphone
data:
title: "💧 Leak detected"
message: Water detected in the basement
group_type: alerts
time_sensitive: truegroup_type decides which thread a notification lands in on the device. Same value, same thread. It is free-form text and case sensitive, so pick something stable such as security, climate or doorbell and reuse it.
icon_url must be an HTTPS URL that is publicly reachable. If you need somewhere to host icons, icons.getnotifyapp.com exists for exactly that. A square image around 512 by 512 works well.
A Live Activity is one Lock Screen tile that updates in place: it appears when a job starts, changes while it runs, and disappears when it ends. The tile appears even when the Notify! app is closed, as long as the app has been opened once on the device.
Two things worth knowing before writing an automation against it:
- A tile lives at most 8 hours. That is Apple's limit, not the API's. The start response reports the deadline as
expiresAt. For anything longer, start a fresh tile when the old one ends. - A countdown costs one call, a progress bar costs one per change. Send
ends_inas a number of seconds and iOS ticks it down locally with no further calls.progresshas to be pushed each time it moves.
| Service | What it does |
|---|---|
notify_api.live_activity_start |
Puts the tile on screen |
notify_api.live_activity_update |
Changes it in place |
notify_api.live_activity_end |
Finishes it |
Every one of them returns the API's response, so response_variable gives you the activityId.
Common fields:
| Field | Type | Description |
|---|---|---|
config_entry_id |
string | Which configured device to use. Optional when only one is set up. |
activity_id |
string | Which tile to address, from the start response. Leave it out to address the device, which is all a single running job needs. Start does not take one. |
title |
string | The tile's heading, up to 120 characters. Required on start. |
body |
string | Second line, up to 300 characters. |
symbol |
string | SF Symbol name for the icon, for example washer.fill. |
tint |
string | Accent colour, #RRGGBB or #AARRGGBB. |
progress |
number | Progress bar, 0 to 100. |
ends_in |
number | Seconds from now for a live countdown, 1 to 86400. |
trailing |
string | Static text where the countdown would be, for a tile with no timer. Up to 40 characters. |
status |
string | Free-form phase word such as running. Up to 40 characters. |
steps |
number | Turns the bar into that many discrete segments, 2 to 20. For a job with named phases rather than a percentage. |
step |
number | How many stages are complete, so 3 of 5 lights the first three. |
metrics |
list | Up to 6 readings rendered side by side where the body line goes. Each is a mapping with label and value, plus optional unit and color. |
button |
mapping | A tappable button: title and url, plus optional open and method. |
new |
boolean | Start only. Starts an extra tile alongside the existing one instead of updating it. |
keep_for |
number | End only. Seconds the finished tile lingers so the result is seen, 0 to 14400. |
progress is clamped rather than refused, so float maths producing 100.4 fills the bar instead of failing the call. tint and a metric's color both take #RRGGBB or #AARRGGBB, and the leading # is optional. ends_in is not clamped: its 24 hour ceiling doubles as the milliseconds trap, so 45 minutes sent as 2700000 is refused with a message saying so.
Because the device address is an upsert, a single running job never needs to touch an activity ID at all. Start, update and end all address the configured device and the API works out which tile is meant:
- action: notify_api.live_activity_start
data:
title: Backup
symbol: externaldrive.fill
tint: "#0A84FF"
progress: 0
- action: notify_api.live_activity_update
data:
progress: 60
status: copying
- action: notify_api.live_activity_end
data:
progress: 100
status: done
keep_for: 300Capture the ID when you need to run more than one tile at a time, or want to be certain which one you are updating:
script:
washer_cycle:
sequence:
- action: notify_api.live_activity_start
data:
title: Laundry
body: Normal wash, warm
symbol: washer.fill
tint: "#7C3AED"
progress: 0
ends_in: 2700
response_variable: tile
- delay: "00:40:00"
- action: notify_api.live_activity_update
data:
activity_id: "{{ tile.activityId }}"
progress: 94
status: rinsing
- action: notify_api.live_activity_end
data:
activity_id: "{{ tile.activityId }}"
progress: 100
status: done
keep_for: 300The start response also carries expiresAt, the point at which iOS removes the tile on its own.
Send only what changed. progress: 94 on its own is a complete update, and anything you leave out stays as it is. An explicit null clears a field:
- action: notify_api.live_activity_update
data:
ends_in: null # removes the countdown
trailing: pausedAn empty string is treated as "not set" rather than as a clear, because that is what a blank text box in the automation editor produces.
Call live_activity_end on every path out of the automation, including the failure ones. Without it a dead tile can sit on the Lock Screen for hours. It is safe to call unconditionally: ending a tile that already finished, or a device with nothing live, is a success rather than an error.
If the user swipes the tile away, that is final. Later updates to it fail with a message saying so, and a looping automation cannot accidentally bring it back.
A metric row replaces the tile's body line with up to six readings:
- action: notify_api.live_activity_start
data:
title: Deploy
symbol: arrow.triangle.2.circlepath
steps: 4
step: 1
metrics:
- label: Tests
value: 412
unit: passed
- label: Coverage
value: "91"
unit: "%"
color: "#34C759"
button:
title: Cancel
url: https://ha.example.com/api/webhook/cancel_deployThe button is fired by the phone, not by Notify!'s servers. With open: false (the default) the phone performs the request itself in the background, so it can reach an address that only resolves on your own network. The URL must be HTTPS either way, so a plain http:// LAN address will not work; a reverse proxy or Nabu Casa URL will.
A Lock Screen widget is one named value that your automations keep fresh: a temperature, a queue depth, a stock level. It has no lifetime to manage and nothing to end, so it is the right place for a reading that should always be visible. Nothing is pushed: the phone reads it whenever iOS refreshes its widgets, roughly every 15 minutes, so it suits readings that drift rather than alerts.
automation:
- alias: Solar widget
triggers:
- trigger: state
entity_id: sensor.solar_power
actions:
- action: notify_api.widget_set
data:
title: Solar
value: "{{ states('sensor.solar_power') }}"
unit: kW
detail: "Peak today {{ states('sensor.solar_peak') }} kW"
symbol: sun.max.fill
tint: "#F5A623"
progress: "{{ (states('sensor.solar_power') | float / 8 * 100) | round }}"| Field | Type | Description |
|---|---|---|
config_entry_id |
string | Which configured device. Optional when only one is set up. |
widget_id |
string | Which widget, from the create response. Leave it out to address the device's widget. |
title |
string | The name in the phone's widget picker. Required the first time, and can be replaced but never cleared. |
value |
string | The headline reading, up to 40 characters. Pre-format it: the widget never does maths on it. |
unit |
string | Small label beside the value, up to 12 characters. |
detail |
string | Secondary line, up to 120 characters. |
symbol |
string | SF Symbol name. |
tint |
string | Accent colour. |
progress |
number | Optional gauge, 0 to 100. |
new |
boolean | Create an additional widget instead of updating the existing one. |
title is only required the first time. After that, updating just the value is a complete call, which is what makes the automation above cheap to run on every state change. A device holds at most 10 widgets. notify_api.widget_delete removes one, and removing a widget that is already gone is reported rather than treated as an error.
A Home Screen widget carries the whole Live Activity content set (title, body, symbol, tint, a progress bar, stages, a countdown, metrics and a button) on a tile that stays. The point is the fan-out: the same fields that drive a Live Activity while a job runs can leave a Home Screen widget behind afterwards.
- action: notify_api.screen_widget_set
data:
title: Backup
symbol: externaldrive.fill
steps: 4
step: 4
status: done
metrics:
- label: Files
value: "{{ states('sensor.backup_files') }}"
- label: Size
value: "{{ states('sensor.backup_size') }}"
unit: GBIt takes every Live Activity field except keep_for, since there is nothing to end, plus screen_widget_id to address one precisely and new to create another. As with a Lock Screen widget, title is required the first time and can never be cleared. A device holds up to 10, and notify_api.screen_widget_delete removes one.
Like a Lock Screen widget it refreshes on the phone's own schedule rather than being pushed. When its content is more than two hours old, or five minutes past a countdown's finish, the phone dims the tile and shows how long ago it was updated, so an automation that stops writing produces a tile that visibly stops being current rather than one that lies. Home Screen widgets are rendered by the Notify! app from version 6.09.03, where they are placed through iOS's own widget picker; creating one through the API never puts anything on screen by itself.
A beacon is reverse monitoring: instead of you telling Notify! that something happened, Notify! tells you when something stopped. Create the beacon in the app (Devices, then Beacons), set how often you expect a ping, then have Home Assistant ping it on a schedule:
automation:
- alias: Tell Notify! that Home Assistant is alive
triggers:
- trigger: time_pattern
minutes: "/15"
actions:
- action: notify_api.beacon_ping
data:
beacon_id: CHK7Q2ZK
ping_token: aB3dE5fG7hJ9kL2Miss the period plus its grace and the beacon goes down and pushes an alert. This is the one failure a notification integration cannot report on its own behalf: if Home Assistant is the thing that died, nothing inside it is left to tell you.
Both halves come from the beacon's ping URL in the app. Paste only the ID into beacon_id and the 15 character token into ping_token. The pair is the credential, so treat it like a password: anyone holding it can mark the job alive. No device ID or device token is involved, which means a ping works for a beacon belonging to any device, including one this integration was never configured with.
Beacons themselves are created and managed in the Notify! app, which is where you set the period, the grace and who gets alerted. The ping URL it gives you is the whole interface from here.
The service does not appear. Restart Home Assistant after installing, then check the integration shows as configured under Settings > Devices & Services. The service name comes from the entry's name, so notify.my_iphone for an entry named "My iPhone".
Notifications do not arrive. Send one from Developer Tools > Actions to see the error directly. Failures raise rather than being swallowed, so the reason appears in the response and in the automation trace. If it reports that Apple rejected the delivery with BadDeviceToken, the device needs to be registered again in the Notify! app; no amount of checking the token will fix that one.
Only some of a group got it. A group notification that reached part of its members still succeeds, and the integration logs a warning saying how many of how many arrived. Look in Settings > System > Logs.
"More than one Notify! Alerts device is configured". A Live Activity service was called with several devices set up and no config_entry_id to pick between them. Set it.
"... is a Device Group", "... is a browser" or "... is a Mac". Live Activities and widgets only appear in the Notify! app on an iPhone or iPad. Use an entry configured with an iPhone's Device ID. Notifications reach all of them, so nothing needs to change there. See Platform support.
A Home Screen widget does not appear. Creating one stores it; placing it is done on the phone, through iOS's widget picker, and needs the Notify! app 6.09.03 or newer.
A widget call reports a conflict. The device holds more than one widget, so addressing the device does not say which. The error lists the widget IDs; pass one as widget_id.
A widget create is refused for a missing title. title is required the first time a widget is made. Send it once, then updates can be just a value.
A beacon ping reports that no beacon matches. An unknown ID and a wrong token answer identically by design. Re-copy the ping URL from the app and check that only the ID went into beacon_id, with the trailing 15 character token in ping_token.
Rate limited while configuring. Credential checks are limited to five a minute per address, and that budget is shared with sending. Wait a minute.
The integration talks to https://push.getnotifyapp.com.
| Endpoint | Used for |
|---|---|
GET /link |
Checking an ID and token pair during setup |
POST /notify-json/{id} |
Sending a notification to a device, browser or group |
POST /live-activity/{id} |
Starting and updating a Lock Screen tile |
DELETE /live-activity/{id} |
Finishing a Lock Screen tile |
POST /widgets/{id} |
Creating and updating a Lock Screen widget |
DELETE /widgets/{id} |
Removing a Lock Screen widget |
POST /screenwidgets/{id} |
Creating and updating a Home Screen widget |
DELETE /screenwidgets/{id} |
Removing a Home Screen widget |
GET /ping/{beaconId}/{token} |
Beacon heartbeat. Carries its own credential, so no device token is sent. |
Notification body, matching the fields documented above:
{
"text": "Your notification message",
"title": "Optional title",
"iconUrl": "https://icons.getnotifyapp.com/icon.png",
"imageUrl": "https://example.com/preview.jpg",
"groupType": "security",
"timeSensitive": true
}Full reference: getnotifyapp.com/apidocs
- No functional changes. The example device name in the documentation and code comments is now a generic one.
The notification action:
- Listed as Send notification using Notify! to name instead of Home Assistant's generic "Send a notification with name", which sat next to the Companion App's action for the same phone as two choices nobody could tell apart
- Every API parameter is now a field of its own:
icon_url,image_url,group_type(shown as Thread) andtime_sensitivejoinmessageandtitle, instead of being hidden in a free-formdatabox. Onlymessageis required, matching the API. - The unused
targetfield is gone from the editor icon_urlandimage_urlmust be HTTPS, and every limit is checked in bytes the way the API counts them, so a bad value is refused while the automation is being written- Automations written for 1.x keep working unchanged,
datamapping included
New:
- Home Screen widgets.
notify_api.screen_widget_setandnotify_api.screen_widget_deleteput the whole Live Activity content set on a Home Screen tile that stays. Needs the Notify! app 6.09.03 or newer.
Fixed:
widget_setwas documented as a Home Screen widget. The endpoint it calls is the Lock Screen widget; it now says so everywhere, and Home Screen widgets have services of their own.- Macs running the Notify Listener are now refused for Live Activities and widgets with a message saying why, including older Macs with an 8 character ID, which are recognised by the platform Notify! reports for them. Newer iPhones with an
IO…ID are allowed, as they should be. - An entry whose name would have replaced one of Home Assistant's own notify actions, such as "Send Message", gets a prefixed action name instead
- Input problems in every service are reported as validation errors rather than integration faults
- Live Activity and widget calls against a browser device are now refused with a message explaining that these are iOS features, instead of being sent and failing as an opaque error. Notifications to browsers are unaffected, as they always were.
- The device's platform is recorded when an entry is saved, so the check knows a browser from an iPhone rather than inferring it from the shape of the ID. Entries saved before this fall back to the ID prefix, and are updated the next time their settings are saved.
- Documented which features reach which targets, under Platform support
Built against the current Notify! Gateway API spec.
New:
- Widgets.
notify_api.widget_setandnotify_api.widget_deleteput a reading on the iPhone Home Screen and keep it current. Unlike a Lock Screen tile a widget persists, so there is no lifetime to manage. - Beacons.
notify_api.beacon_pingsends a heartbeat, so Notify! can alert you when Home Assistant itself stops running. Beacons are created in the Notify! app. - Staged tile progress.
stepsandstepturn the progress bar into discrete segments, for a job with named phases rather than a percentage. - Tile metric rows.
metricsrenders up to 6 readings side by side where the body line goes, each with an optional unit and its own colour. - Tile buttons.
buttonadds a tappable action. The phone fires it rather than Notify!'s servers, so withopenoff it can reach an HTTPS endpoint on your own network. live_activity_endnow accepts the full set of content fields, so a tile can be left in a final state while it lingers.
Changed:
tint, and a metric'scolor, now accept a bareRRGGBBas well as#RRGGBB, matching the APIprogressis clamped to 0 to 100 rather than refused, so float maths producing100.4fills the bar instead of failing the call.ends_inis still range checked, because its ceiling is what catches milliseconds sent where seconds belong.- A widget's
valueand a metric'svalueaccept a bare number and store it as text, so a templated sensor state does not need quoting
New:
- Live Activities.
live_activity_start,live_activity_updateandlive_activity_enddrive a Lock Screen tile from an automation, with progress, countdowns, SF Symbols and tint colours. Each returns the activity ID so several tiles can run at once. image_urlfor a hero image shown when a notification is expandedtime_sensitiveto let a notification break through Focus and Do Not Disturb- The API's own camelCase field names are accepted alongside the snake_case ones
- Defaults for image and time sensitive delivery, alongside the existing title, icon and thread defaults
Fixed:
- The defaults set under Configure were stored but never applied to notifications. They now are.
- Removing the integration left its notification service registered, because unloading derived a different service name than setup had used
- A name containing an apostrophe or an accent produced an unusable service name
- The same device could be added twice, registering two services fighting over one name
- A rejected token emptied the setup form, so the ID had to be pasted again to fix a one character mistake. Both forms now keep what you typed.
- Two entries whose names reduce to the same service name are now called out in the log instead of one quietly replacing the other
API and reliability:
- Moved to the current API hostname,
push.getnotifyapp.com. The previous hostname continues to work. - Setup and reconfiguration now validate through
GET /linkand report the device or group name, instead of pushing a real notification to the phone every time the settings were saved - Failed notifications raise instead of being logged and swallowed, so the reason shows up in the automation trace rather than only in the log
- Delivery failures report Apple's own rejection reason, such as
BadDeviceToken, instead of a generic failure - Group notifications that reached only some of their members are logged as a warning instead of reported as a plain success
- A redirect from the API is reported as an actionable message instead of being followed, since the token travels in the query string
- IDs are percent encoded, so an ID containing a space no longer produces a malformed request
- API responses are no longer logged above debug level, since a group response lists every member device ID
- Initial release: notify service, UI configuration, custom naming, title, icons and threading
MIT. See LICENSE.
- Issues: GitHub
- API reference: getnotifyapp.com/apidocs
- Icon hosting: icons.getnotifyapp.com
Made with love by Pingie.com