# Immich Album Watcher Blueprint

This blueprint monitors Immich album changes and sends notifications when assets (photos/videos) are added to specified albums. Designed to be used in pair with the [Immich Album Watcher](https://github.com/DolgolyovAlexei/haos-hacs-immich-album-watcher) integration.

## Features

- Monitor specific albums by ID (whitelist)
- Filter by asset type (track images only, videos only, or both)
- Filter by favorites only (only notify about favorite assets)
- Sort assets by date, rating, name, or keep original order
- Send notifications to multiple targets simultaneously
- Customizable notification messages with template variables
- Separate templates for image and video assets
- Optional: include people detected in photos
- Optional: include detailed asset list with per-item formatting
- Support for multiple change types (assets added, removed, changed)
- Optional: send photos/videos as Telegram media attachments
- Optional: periodic summary notifications with album list and share URLs
- Optional: memory mode (On This Day) for photos from today's date in previous years

## Event Data from Immich

### Assets Added/Removed/Changed Events

| Field | Description |
|-------|-------------|
| `hub_name` | Name of the Immich hub/instance that sent the event |
| `album_id` | Album ID |
| `album_name` | Album name |
| `album_url` | Public URL to view the album (only if album has shared link) |
| `change_type` | Type of change (assets_added, assets_removed, changed) |
| `added_count` | Number of assets added |
| `removed_count` | Number of assets removed |
| `added_assets` | List of added assets (see Added Assets Fields below) |
| `removed_assets` | List of removed asset IDs |
| `people` | List of all people detected in the album |

### Album Renamed Event

| Field | Description |
|-------|-------------|
| `hub_name` | Name of the Immich hub/instance that sent the event |
| `album_id` | Album ID |
| `old_name` | Previous album name |
| `new_name` | New album name |
| `album_url` | Public URL to view the album (only if album has shared link) |

### Album Deleted Event

| Field | Description |
|-------|-------------|
| `hub_name` | Name of the Immich hub/instance that sent the event |
| `album_id` | Album ID |
| `album_name` | Album name that was deleted |

## Added Assets Fields

Each item in `added_assets` contains:

| Field | Description |
|-------|-------------|
| `id` | Unique asset ID |
| `type` | Type of asset (IMAGE or VIDEO) |
| `filename` | Original filename of the asset |
| `created_at` | Date/time when the asset was originally created |
| `owner` | Display name of the user who owns the asset |
| `owner_id` | Unique ID of the user who owns the asset |
| `description` | Description/caption (user-added in Immich, or EXIF fallback) |
| `is_favorite` | Whether the asset is marked as favorite (true or false) |
| `rating` | User rating of the asset (1-5 stars, or null if not rated) |
| `url` | Public URL to view the asset (only if album has shared link) |
| `download_url` | Direct download URL for the original file (if shared link exists) |
| `playback_url` | Video playback URL (for VIDEO assets only, if shared link exists) |
| `photo_url` | Photo preview URL (for IMAGE assets only, if shared link exists) |
| `people` | List of people detected in this specific asset |
| `city` | City name from reverse geocoding (if available) |
| `state` | State/region name from reverse geocoding (if available) |
| `country` | Country name from reverse geocoding (if available) |

## Message Template Variables

All message templates support these placeholder variables (use single braces):

| Variable | Description |
|----------|-------------|
| `{album_name}` | Name of the album |
| `{album_url}` | Public URL to view the album (empty if no shared link) |
| `{album_created}` | Album creation date (formatted with date format) |
| `{album_updated}` | Album last update date (formatted with date format) |
| `{added_count}` | Number of assets added |
| `{removed_count}` | Number of assets removed |
| `{people}` | Comma-separated list of people detected |
| `{assets}` | Formatted list of added assets (using asset item template) |
| `{video_warning}` | Warning about video size limits (Telegram only, empty otherwise) |
| `{common_date}` | Common date formatted with template if all assets share same date, empty otherwise |
| `{common_location}` | Common location formatted with template if all assets share same location (requires city, state, country), empty otherwise |

## Asset Item Template Variables

These variables can be used in the image and video asset templates. Also used for Telegram media captions.

| Variable | Description |
|----------|-------------|
| `{filename}` | Original filename of the asset |
| `{description}` | Description/caption (user-added in Immich, or EXIF fallback) |
| `{type}` | Asset type (IMAGE or VIDEO) |
| `{created}` | Creation date/time (always shown) |
| `{created_if_unique}` | Creation date/time formatted with template if dates differ, empty if all same |
| `{year}` | Year the asset was created (4-digit, e.g., 2024) |
| `{owner}` | Owner display name |
| `{url}` | Public URL to view the asset (empty if no shared link) |
| `{download_url}` | Direct download URL for the original file |
| `{photo_url}` | Photo preview URL (for IMAGE assets only) |
| `{playback_url}` | Video playback URL (for VIDEO assets only) |
| `{people}` | People detected in this asset |
| `{album_name}` | Name of the album |
| `{album_created}` | Album creation date (formatted with date format) |
| `{album_updated}` | Album last update date (formatted with date format) |
| `{is_favorite}` | Favorite indicator (using template) if asset is favorite, empty otherwise |
| `{rating}` | User rating (1-5) or empty if not rated |
| `{location}` | Formatted location string (using location format template), empty if location data incomplete |
| `{location_if_unique}` | Location formatted with template if locations differ between assets, empty if all same or data incomplete |
| `{city}` | City name from reverse geocoding, empty if not available |
| `{state}` | State/region name from reverse geocoding, empty if not available |
| `{country}` | Country name from reverse geocoding, empty if not available |

## Telegram Media Attachments

When enabled, photos/videos are sent as media attachments to Telegram using the `immich_album_watcher.send_telegram_notification` service.

### Supported Recipients

Select input_text entities containing Telegram chat IDs. Can be user IDs (positive) or group IDs (negative).

### Requirements

- Immich Album Watcher integration must be configured with Telegram bot token
- Immich album must have a shared link (to generate public asset URLs)

### Behavior

- First sends a text notification message to each Telegram chat
- Then sends photos/videos as media groups (albums) as replies to that message
- Uses transcoded/optimized versions of assets when available (not original files)
- Media is downloaded from Immich and uploaded to Telegram (bypasses CORS)
- Large media lists are automatically split into multiple groups (2-10 items per group)
- Optional chat action indicator (typing, uploading photo/video) while processing
- Optional maximum asset size filter to skip large files

### Limitations

- Only assets with valid public URLs will be sent
- Telegram has a 50 MB file size limit for media (configurable 1-50 MB filter to skip large assets)
- Optional video warning can be shown when videos are present
- Media captions use the Image/Video Asset Templates

## Periodic Summary

Sends a summary notification of tracked albums at configured times. Album names and share URLs are automatically read from the Album ID Entity's `album_name` and `share_url` attributes (if available). You can configure multiple notification times (e.g., "12:00, 18:00") using comma-separated 24-hour format with leading zeros.

Use **Summary Interval** to control how often summaries are sent (default: every day). Set it to `7` for weekly, `14` for bi-weekly, etc. The **Summary Start Date** anchors the interval — summaries are sent on that date and every N days after. For example, setting the start date to a Monday with an interval of 7 sends summaries every Monday.

When Telegram media is enabled, an optional image can be attached to the summary message. By default, the official Immich logo is used. Set the **Summary Image URL** to empty to send text-only notifications.

### Summary Message Template Variables

| Variable | Description |
|----------|-------------|
| `{albums}` | Formatted list of albums (using album item template) |
| `{album_count}` | Number of tracked albums |

### Album Item Template Variables

| Variable | Description |
|----------|-------------|
| `{album_name}` | Name of the album |
| `{album_id}` | Album ID |
| `{album_url}` | Share URL for the album |
| `{album_created}` | Album creation date (formatted with date format) |
| `{album_updated}` | Album last update date (formatted with date format) |

### Testing Periodic Summary

To test the periodic summary without waiting for the scheduled time, fire this event from Developer Tools > Events:

- **Event type**: `immich_album_watcher_test_periodic_summary`

To target a specific automation, set its Automation ID in config and include it in the event data:

- **Event data**: `{"automation_id": "your-automation-id"}`

## Scheduled Assets

Sends scheduled notifications with existing assets from tracked albums at configured times. Uses the `immich_album_watcher.get_assets` service to fetch assets. You can configure multiple notification times (e.g., "09:00, 21:00") using comma-separated 24-hour format with leading zeros.

### Album Modes

| Mode | Description |
|------|-------------|
| `per_album` | Send separate notifications for each tracked album |
| `combined` | Fetch assets from all albums into one notification |
| `random` | Pick one random album each time |

### Asset Filter Options

| Option | Description |
|--------|-------------|
| `limit` | Maximum number of assets to fetch (1-100) |
| `favorite_only` | Only fetch favorite assets |
| `asset_type` | Filter by type (all, photo, video) |
| `order_by` | Sort by (random, date, rating, name) |
| `order` | Sort direction (ascending, descending) |
| `filter_min_rating` | Minimum rating filter (1-5, 0 = no filter) |
| `min_date` | Assets created on or after this date (YYYY-MM-DD) |
| `max_date` | Assets created on or before this date (YYYY-MM-DD) |

### Scheduled Assets Message Template Variables

| Variable | Description |
|----------|-------------|
| `{album_name}` | Name of the album |
| `{album_url}` | Share URL for the album |
| `{album_created}` | Album creation date (empty in combined mode) |
| `{album_updated}` | Album last update date (empty in combined mode) |
| `{asset_count}` | Number of assets fetched |
| `{assets}` | Formatted list of assets (using asset item template) |
| `{common_date}` | Common date if all assets share same date |
| `{common_location}` | Common location if all assets share same location |

### Testing Scheduled Assets

To test without waiting for the scheduled time, fire this event:

- **Event type**: `immich_album_watcher_test_scheduled_assets`

To target a specific automation, set its Automation ID in config and include it in the event data:

- **Event data**: `{"automation_id": "your-automation-id"}`

## Memory Mode (On This Day)

Send scheduled notifications with photos taken on today's date in previous years - similar to "On This Day" or "Memories" features in photo apps. This is a separate feature from Scheduled Assets with its own schedule and settings.

### Memory Mode Options

| Option | Description |
|--------|-------------|
| `enable_memory_mode` | Enable/disable memory notifications |
| `notification_times` | Comma-separated times in 24-hour format (e.g., "09:00, 18:00") |
| `album_mode` | per_album, combined, or random |
| `limit` | Maximum number of assets to fetch (1-100) |
| `favorite_only` | Only fetch favorite assets |
| `asset_type` | Filter by type (all, photo, video) |
| `min_rating` | Minimum rating filter (1-5, 0 = no filter) |

Memory notifications are sent at the configured times. Times must use 24-hour format with leading zeros (e.g., "09:00" not "9:00").

### Memory Mode Message Template Variables

| Variable | Description |
|----------|-------------|
| `{album_name}` | Name of the album |
| `{album_url}` | Share URL for the album |
| `{album_created}` | Album creation date (empty in combined mode) |
| `{album_updated}` | Album last update date (empty in combined mode) |
| `{asset_count}` | Number of memory assets fetched |
| `{assets}` | Formatted list of assets (using asset item template) |
| `{common_date}` | Common date if all assets share same date |
| `{common_location}` | Common location if all assets share same location |

### Testing Memory Mode

To test without waiting for the scheduled time, fire this event:

- **Event type**: `immich_album_watcher_test_memory_mode`

To target a specific automation, set its Automation ID in config and include it in the event data:

- **Event data**: `{"automation_id": "your-automation-id"}`

## Author

Alexei Dolgolyov (dolgolyov.alexei@gmail.com)