284 lines
13 KiB
Markdown
284 lines
13 KiB
Markdown
# 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)
|