Add custom notification icons for automations by Roei-Bracha · Pull Request #4672 · home-assistant/iOS

Roei-Bracha · 2026-05-27T17:23:20Z

This PR adds support for custom notification icons (iMessage-style communication notifications) when a push payload contains notification_icon or icon_url. Matches the Android companion app's payload schema.

Simulator Screenshot - iPhone 16e - 2026-05-28 at 22 07 51

Testing status

This currently works with local push. I verified it in the iOS simulator by sending a Home Assistant notification with:

data:
  notification_icon: mdi:cellphone

After enabling local push for the simulator server, the notification displayed the custom cellphone icon instead of the app icon.

Nabu Casa / remote push rollout

For Nabu Casa cloud push and other non-local notifications to work, the push relay/server must deploy the matching SharedPush parser change from this PR. The server-side notification normalization currently needs to:

copy icon_url, notification_icon, notification_icon_color, and color from the Home Assistant notification data object into the top-level APNs custom payload
set aps["mutable-content"] = true when either icon_url or notification_icon is present, so iOS launches the notification service extension

Expected APNs payload shape for notification_icon: mdi:cellphone:

{
  "aps": {
    "alert": {
      "title": "Phone",
      "body": "test"
    },
    "sound": "default",
    "mutable-content": true
  },
  "notification_icon": "mdi:cellphone",
  "notification_icon_color": "#FFFFFF",
  "color": "#03A9F4"
}

Until that server-side relay code is deployed, cloud pushes can still arrive without notification_icon and without mutable-content, so they will keep showing the normal app icon.

home-assistant

Hi @Roei-Bracha

It seems you haven't yet signed a CLA. Please do so here.

Once you do that we will be able to review and accept this pull request.

Thanks!

home-assistant · 2026-05-27T17:23:26Z

Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍

Learn more about our pull request process.

Copilot

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds end-to-end support for custom notification “sender avatars” on iOS by parsing existing Android payload fields (notification_icon, color, icon_url) and decorating notifications into iOS Communication Notification style using INSendMessageIntent, with caching + tests and accompanying design/plan docs.

Changes:

Introduces NotificationSenderInfo + NotificationSenderParser to extract sender/icon info from UNNotificationContent.userInfo.
Adds NotificationCommunicationDecorator to apply Communication Notification styling (MDI render or downloaded URL icon) and a disk-backed NotificationIconCache.
Wires the decorator into the Notification Service Extension pipeline and adds unit tests + a sample .apns payload.

Reviewed changes

Copilot reviewed 15 out of 16 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
docs/superpowers/specs/2026-05-24-custom-notification-icons-design.md	New design spec describing payload contract, architecture, caching, and compliance considerations
docs/superpowers/plans/2026-05-24-custom-notification-icons.md	New task-by-task implementation plan and test strategy
Sources/Shared/Notifications/NotificationSender/NotificationSenderInfo.swift	Defines parsed sender/icon value type used by parser/decorator
Sources/Shared/Notifications/NotificationSender/NotificationSenderParser.swift	Parses `notification_icon` / `icon_url` / colors into `NotificationSenderInfo`
Sources/Shared/Notifications/NotificationSender/NotificationIconCache.swift	Adds disk cache with App Group + cross-process coordination
Sources/Shared/Notifications/NotificationSender/NotificationCommunicationDecorator.swift	Builds/donates `INSendMessageIntent` and applies `content.updating(from:)` with avatar image generation
Sources/Shared/Environment/Environment.swift	Registers decorator in DI container (`Current`)
Sources/Extensions/NotificationService/NotificationService.swift	Adds decorator step after existing attachment pipeline
Sources/Extensions/NotificationContent/Resources/TestNotifications/communication_notification.apns	Adds reproducible test payload for manual simulator/device verification
Tests/Shared/NotificationSender/NotificationSenderInfoTests.swift	Unit tests for value-type equality
Tests/Shared/NotificationSender/NotificationSenderParserTests.swift	Unit tests for field precedence, defaults, and malformed inputs
Tests/Shared/NotificationSender/NotificationIconCacheTests.swift	Unit tests for cache behavior + eviction + key stability
Tests/Shared/NotificationSender/NotificationCommunicationDecoratorTests.swift	Unit tests for intent construction, conversation grouping, URL download/cache behavior
HomeAssistant.xcodeproj/project.pbxproj	Adds new files to targets/groups (and incidental project-file churn)
Gemfile	Adds `abbrev` gem dependency
Gemfile.lock	Locks `abbrev` and bumps Bundler version

home-assistant

Hi @Roei-Bracha

It seems you haven't yet signed a CLA. Please do so here.

Once you do that we will be able to review and accept this pull request.

Thanks!

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Copilot

Pull request overview

Copilot reviewed 13 out of 14 changed files in this pull request and generated 2 comments.

bgoncal · 2026-05-28T09:43:59Z

For the linter you can run bundle exec fastlane autocorrect

bgoncal · 2026-05-28T14:04:04Z

Please mark as "Ready for review" after you finish

…heck

- Support 'notification_icon', 'notification_icon_color', and 'color' keys in the push payload. - Promote custom notification icon fields in local push / websocket parser. - Register 'INSendMessageIntent' in NotificationService Extension Info.plist to support communication notification decoration. - Ensure notification intent donation completes before finishing decoration. - Add unit tests for local push event, notification sender parser, and legacy parser.

…e URL cache key collision

Stale

bgoncal · 2026-06-16T15:56:34Z

@Roei-Bracha can you check the conflicts?

bgoncal · 2026-06-22T12:26:40Z

@Roei-Bracha are you still planning to work on it?

…proved readability

Roei-Bracha · 2026-06-22T19:05:37Z

@bgoncal, sorry I couldn't get to this earlier; I believe it should be fine now.

codecov · 2026-06-22T19:32:44Z

Codecov Report

❌ Patch coverage is 92.17391% with 18 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (main@525dc0b). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
...ionSender/NotificationCommunicationDecorator.swift	85.85%	14 Missing ⚠️
...ons/NotificationSender/NotificationIconCache.swift	95.71%	3 Missing ⚠️
...ns/NotificationSender/NotificationSenderInfo.swift	94.44%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4672   +/-   ##
=======================================
  Coverage        ?   45.62%           
=======================================
  Files           ?      279           
  Lines           ?    17068           
  Branches        ?        0           
=======================================
  Hits            ?     7787           
  Misses          ?     9281           
  Partials        ?        0

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

bgoncal · 2026-06-29T09:48:05Z

@Roei-Bracha Sorry, I've been very busy these last days, I added a reminder to check this PR during this week, meanwhile can you check the conflicts and resolve them?

bgoncal

Review the comments added (maybe it came from an AI? they are usually verbose), reduce to only add comments to content not understandable by reading the code (and of course avoid adding non-obvious code)

bgoncal · 2026-07-01T13:45:49Z


-        guard let server = Current.servers.server(for: request.content), let api = Current.api(for: server) else {
-            contentHandler(request.content)
+        guard let server = Current.servers.server(for: request.content),


Use guard let here to improve readability

bgoncal · 2026-07-01T13:46:50Z

+    case iconURL = "icon_url"
+    case notificationIcon = "notification_icon"
+    case notificationIconColor = "notification_icon_color"
+    case color


Double check if this does not exist somewhere else in the code base, live activity just has added these keys as well

bgoncal · 2026-07-01T14:02:52Z

+        }
+    }
+
+    /// MDI path is synchronous (no network). URL path downloads, caches, and downsamples the avatar.


Suggested change

/// MDI path is synchronous (no network). URL path downloads, caches, and downsamples the avatar.

Roei-Bracha · 2026-07-01T14:09:46Z

Sorry, I won't be able to work on this right away. I'll be able to start on it in about two weeks. @bgoncal

bgoncal · 2026-07-01T14:11:06Z

@Roei-Bracha No problem, thanks for letting me know, I'm here to help if you need, also in discord (@ bgoncal2)

Copilot AI review requested due to automatic review settings May 27, 2026 17:23

home-assistant Bot previously requested changes May 27, 2026

View reviewed changes

home-assistant Bot added the cla-needed label May 27, 2026

home-assistant Bot marked this pull request as draft May 27, 2026 17:23

Add custom notification icons for automations

7ccd851

Copilot AI reviewed May 27, 2026

View reviewed changes

Roei-Bracha force-pushed the feature/custom-notification-icons branch from 7eb3bac to 7ccd851 Compare May 27, 2026 17:26

home-assistant Bot previously requested changes May 27, 2026

View reviewed changes

home-assistant Bot added cla-recheck cla-signed and removed cla-recheck cla-needed labels May 27, 2026

Address review comments for custom notification icons

8937acb

Roei-Bracha requested a review from Copilot May 27, 2026 17:43

Merge branch 'main' into feature/custom-notification-icons

2178307

Copilot AI reviewed May 27, 2026

CCOSTAN mentioned this pull request May 28, 2026

Joanna Idea Scout - 2026-05-28 CCOSTAN/Home-AssistantConfig#1771

Closed

bgoncal requested a review from Copilot May 28, 2026 09:35

Copilot started reviewing on behalf of bgoncal May 28, 2026 09:35 View session

Copilot AI reviewed May 28, 2026

View reviewed changes

Comment thread Sources/Shared/Notifications/NotificationSender/NotificationSenderInfo.swift

Comment thread Sources/Shared/Notifications/NotificationSender/NotificationCommunicationDecorator.swift

Roei-Bracha added 7 commits May 28, 2026 19:24

Wrap CarPlay assist session actionButtons configuration in compiler c…

1b7f5d8

…heck

Support notification decoration without API context for local testing

f015944

Add Communication Notifications entitlement to extensions

0273aed

Decorate local push notifications in LocalPushManager

5a0c9e2

fix: address PR review comments for Equatable conformance and relativ…

09612be

…e URL cache key collision

Merge branch 'main' into feature/custom-notification-icons

bde999e

Roei-Bracha marked this pull request as ready for review May 28, 2026 19:48

This was referenced May 29, 2026

Joanna Idea Scout - 2026-05-29 CCOSTAN/Home-AssistantConfig#1772

Closed

Track iOS custom notification icon support for local alerts CCOSTAN/Home-AssistantConfig#1773

Open

bgoncal requested changes Jun 1, 2026

View reviewed changes

home-assistant Bot marked this pull request as draft June 1, 2026 09:25

Roei-Bracha added 2 commits June 1, 2026 18:22

Address notification icon review feedback

3c833fb

Merge branch 'main' into feature/custom-notification-icons

db26f5b

Roei-Bracha marked this pull request as ready for review June 1, 2026 15:35

home-assistant Bot requested a review from bgoncal June 1, 2026 15:35

Merge branch 'main' into feature/custom-notification-icons

992b1fe

Roei-Bracha added 2 commits June 22, 2026 18:16

Merge upstream/main into feature/custom-notification-icons

6a6d3ee

Refactor closure to capture notificationCommunicationDecorator for im…

0ac5890

…proved readability

CCOSTAN mentioned this pull request Jun 23, 2026

Joanna Idea Scout - 2026-06-23 CCOSTAN/Home-AssistantConfig#1796

Closed

CCOSTAN mentioned this pull request Jul 1, 2026

Joanna Idea Scout - 2026-07-01 CCOSTAN/Home-AssistantConfig#1811

Closed

bgoncal requested changes Jul 1, 2026

View reviewed changes

home-assistant Bot marked this pull request as draft July 1, 2026 14:04

CCOSTAN mentioned this pull request Jul 2, 2026

Joanna Idea Scout - 2026-07-02 CCOSTAN/Home-AssistantConfig#1814

Closed

Uh oh!

Conversation

Roei-Bracha commented May 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Testing status

Nabu Casa / remote push rollout

Uh oh!

home-assistant Bot left a comment

Choose a reason for hiding this comment

Uh oh!

home-assistant Bot commented May 27, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

home-assistant Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

bgoncal commented May 28, 2026

Uh oh!

bgoncal commented May 28, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bgoncal commented Jun 16, 2026

Uh oh!

bgoncal commented Jun 22, 2026

Uh oh!

Roei-Bracha commented Jun 22, 2026

Uh oh!

codecov Bot commented Jun 22, 2026

Codecov Report

Uh oh!

bgoncal commented Jun 29, 2026

Uh oh!

bgoncal left a comment

Choose a reason for hiding this comment

Uh oh!

bgoncal Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

bgoncal Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

bgoncal Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

Roei-Bracha commented Jul 1, 2026

Uh oh!

bgoncal commented Jul 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Roei-Bracha commented May 27, 2026 •

edited

Loading