haos-hacs-immich-album-watcher/plans/phase-10-telegram-commands.md

# Phase 10: Telegram Bot Commands

**Status**: Pending
**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