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.

Roei-Bracha · 2026-05-28T19:42:22Z

+public struct NotificationSenderInfo: Equatable {
+    public enum Source: Equatable {
+        /// User-supplied image URL. `needsAuth` is true when the URL string begins with `/`
+        /// (matching the rule in `NotificationAttachmentParserURL`).
+        case iconURL(URL, needsAuth: Bool)
+
+        /// Built-in Material Design Icon, rendered onto a colored square.
+        /// `background` defaults to `AppConstants.tintColor` when `color` is absent.
+        /// `foreground` defaults to `.white` when `notification_icon_color` is absent.
+        case mdi(
+            name: String,
+            background: UIColor,
+            foreground: UIColor,
+            colorString: String?,
+            iconColorString: String?
+        )


Fixed. We have implemented a manual == operator for NotificationSenderInfo.Source that compares MDI icon names, string values (colorString, iconColorString) directly if present, and safely compares UIColors via isEqual as a fallback. This guarantees clean and stable synthesized Equatable behavior.

Roei-Bracha · 2026-05-28T19:42:26Z

+        case let .iconURL(url, needsAuth):
+            let cacheKey = notificationIconCacheKey(for: url)
+            if let cached = cache.data(forKey: cacheKey) {
+                return .value(INImage(imageData: cached))
+            }


Fixed. We modified notificationIconCacheKey(for:serverID:) to accept an optional serverID: String? = nil parameter. When resolving relative/authenticated icon URLs, we extract the active server's unique identifier from the HomeAssistantAPI instance and include it in the hashed string, preventing namespace collisions and leaks across multiple servers in the shared App Group container.

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

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

View reviewed changes

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

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

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!

Roei-Bracha May 28, 2026

Choose a reason for hiding this comment

Uh oh!

Roei-Bracha May 28, 2026

Choose a reason for hiding this comment

Uh oh!

bgoncal commented May 28, 2026

Uh oh!

bgoncal commented May 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Roei-Bracha commented May 27, 2026 •

edited

Loading