Add custom notification icons for automations

[Roei-Bracha]

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.

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]

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]

For the linter you can run bundle exec fastlane autocorrect

[bgoncal]

Please mark as "Ready for review" after you finish

Stale