alexei.dolgolyov
e6ff0a423a
All checks were successful
Validate / Hassfest (push) Successful in 3s
Phase 10 — Telegram Bot Commands: - Add commands_config JSON field to TelegramBot model (enabled cmds, default count, response mode, rate limits, locale) - Create command handler with 14 commands: /status, /albums, /events, /summary, /latest, /memory, /random, /search, /find, /person, /place, /favorites, /people, /help - Add search_smart, search_metadata, search_by_person, get_random, download_asset, get_asset_thumbnail to ImmichClient - Auto-register commands with Telegram setMyCommands API (EN+RU) - Rate limiting per chat per command category - Media mode: download thumbnails and send as photos to Telegram - Webhook handler routes /commands before falling through to AI chat - Frontend: expandable Commands section per bot with checkboxes, count/mode/locale settings, rate limit inputs, sync button Phase 11 — Snackbar Notifications: - Create snackbar store (snackbar.svelte.ts) with $state rune - Create Snackbar component with fly/fade transitions, typed colors - Mount globally in +layout.svelte - Replace all alert() calls with typed snackbar notifications - Add success snacks to all CRUD operations across all pages - 4 types: success (3s), error (5s), info (3s), warning (4s) - Max 3 visible, auto-dismiss, manual dismiss via X button Both: Add ~30 i18n keys (EN+RU) for commands UI and snack messages. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
151 lines
6.2 KiB
Markdown
151 lines
6.2 KiB
Markdown
# Phase 10: Telegram Bot Commands
|
|
|
|
**Status**: Done
|
|
**Parent**: [primary-plan.md](primary-plan.md)
|
|
|
|
---
|
|
|
|
## Goal
|
|
|
|
Define and implement Telegram bot commands that users can invoke directly from chat to interact with the Immich Watcher system. The server auto-registers commands with Telegram's BotFather API whenever the command config changes.
|
|
|
|
---
|
|
|
|
## Proposed Commands
|
|
|
|
### Informational
|
|
|
|
- `/status` — Show tracker status (active trackers, last event, server health)
|
|
- `/albums` — List tracked albums with asset counts
|
|
- `/events [N]` — Show last N events (default 5)
|
|
|
|
### On-Demand Notifications
|
|
|
|
- `/summary` — Trigger periodic summary now
|
|
- `/latest [album] [N]` — Show latest assets from an album (or all)
|
|
- `/memory` — Trigger "On This Day" memory notification now
|
|
- `/random [album] [N]` — Send random photo(s) from an album
|
|
|
|
### Asset Browsing
|
|
|
|
**IMPORTANT**: All asset commands MUST only search within albums that are tracked by the tracker(s) associated with the bot's target. Never expose assets from untracked albums.
|
|
|
|
- `/search <query> [N]` — Semantic/smart search via Immich CLIP ("dog on beach", "birthday party")
|
|
- `/find <text> [N]` — Text search by filename, description
|
|
- `/ocr <text> [N]` — Search by text visible in photos/videos (OCR)
|
|
- `/person <name> [N]` — Find photos with a specific person
|
|
- `/place <location> [N]` — Find photos by city/country/location
|
|
- `/favorites [album] [N]` — Show favorite assets
|
|
- `/people` — List detected people across albums
|
|
|
|
All browsing commands accept optional `[N]` count limit (default configurable per bot, max: 20).
|
|
|
|
### Management
|
|
|
|
- `/help` — Show available commands with descriptions
|
|
|
|
---
|
|
|
|
## Configuration (per bot)
|
|
|
|
### Command Settings
|
|
|
|
- **Enabled commands**: checkboxes per command (enable/disable individually)
|
|
- **Default result count**: 1-20 (default: 5) — used when `[N]` is omitted
|
|
- **Response mode**: `media` (send photos) or `text` (send links) — default per bot, overridable per command with inline suffix like `/search sunset --text`
|
|
- **Rate limiting**: configurable cooldown per command category per chat (e.g. 30s for search, 10s for info). 0 = no limit.
|
|
- **Bot locale**: EN/RU — used for command descriptions registered with Telegram and response messages
|
|
|
|
---
|
|
|
|
## Tasks
|
|
|
|
### 1. Command registry model `[ ]`
|
|
|
|
- Add `commands_config` JSON field to TelegramBot model:
|
|
```json
|
|
{
|
|
"enabled": ["status", "albums", "events", "search", "find", "help", ...],
|
|
"default_count": 5,
|
|
"response_mode": "media",
|
|
"rate_limits": {"search": 30, "find": 30, "ocr": 30, "default": 10},
|
|
"locale": "en"
|
|
}
|
|
```
|
|
- Default config set on bot registration
|
|
|
|
### 2. Command descriptions & localization `[ ]`
|
|
|
|
- Store command descriptions in both EN and RU:
|
|
```
|
|
status: "Show tracker status" / "Показать статус трекеров"
|
|
albums: "List tracked albums" / "Список отслеживаемых альбомов"
|
|
events: "Show recent events" / "Показать последние события"
|
|
summary: "Send album summary now" / "Отправить сводку альбомов"
|
|
latest: "Show latest photos" / "Показать последние фото"
|
|
memory: "On This Day memories" / "Воспоминания за этот день"
|
|
random: "Send random photo" / "Отправить случайное фото"
|
|
search: "Smart search (AI)" / "Умный поиск (AI)"
|
|
find: "Search by text" / "Поиск по тексту"
|
|
ocr: "Search text in photos" / "Поиск текста на фото"
|
|
person: "Find photos of person" / "Найти фото человека"
|
|
place: "Find photos by location" / "Найти фото по месту"
|
|
favorites: "Show favorites" / "Показать избранное"
|
|
people: "List detected people" / "Список людей"
|
|
help: "Show available commands" / "Показать доступные команды"
|
|
```
|
|
- Bot response messages also localized based on bot locale setting
|
|
- Descriptions editable per bot in the UI (override defaults)
|
|
|
|
### 3. Auto-register commands with Telegram `[ ]`
|
|
|
|
- Call `setMyCommands` API when commands config changes
|
|
- Call on bot creation and on config update
|
|
- Use bot locale to select which descriptions to register
|
|
- Telegram supports `setMyCommands` with `language_code` parameter — register both EN and RU descriptions simultaneously
|
|
|
|
### 3. Webhook command handler `[ ]`
|
|
|
|
- Extend existing webhook handler to route `/command` messages
|
|
- Parse command + arguments + optional count `[N]`
|
|
- Check if command is enabled for this bot
|
|
- Check rate limit per chat per command
|
|
- Execute corresponding logic (reuse existing services)
|
|
- Return response in configured mode (media or text)
|
|
|
|
### 4. Implement each command `[ ]`
|
|
|
|
- `/status`, `/albums`, `/events` — read from DB
|
|
- `/summary`, `/memory` — call watcher/notifier services
|
|
- `/latest`, `/random` — fetch from Immich via core client, scoped to tracked albums
|
|
- `/search` — call Immich `POST /api/search/smart` (CLIP), scoped to tracked albums
|
|
- `/find` — call Immich `POST /api/search/metadata`, scoped to tracked albums
|
|
- `/ocr` — call Immich `POST /api/search/smart` with OCR context, scoped to tracked albums
|
|
- `/person` — filter tracked album assets by person name
|
|
- `/place` — filter tracked album assets by city/country
|
|
- `/favorites` — filter tracked album assets by is_favorite
|
|
- `/people` — aggregate people from all tracked album assets
|
|
- `/help` — auto-generated from enabled commands with descriptions
|
|
|
|
### 5. Frontend: command config per bot `[ ]`
|
|
|
|
- On telegram-bots page, expandable "Commands" section per bot
|
|
- Checkboxes to enable/disable each command
|
|
- Default count slider (1-20)
|
|
- Response mode toggle (media/text)
|
|
- Rate limit inputs per category
|
|
- Bot locale selector (EN/RU)
|
|
- "Sync Commands" button (calls setMyCommands)
|
|
|
|
---
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] Commands registered with Telegram and visible in bot menu
|
|
- [ ] Each command returns a useful response (media or text based on config)
|
|
- [ ] Commands auto-sync when config changes
|
|
- [ ] Admin can enable/disable commands per bot via UI
|
|
- [ ] Rate limiting works per chat per command
|
|
- [ ] All asset commands scoped to tracked albums only
|
|
- [ ] Count limit configurable per bot with per-command override
|