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

Phase 10: Telegram Bot Commands

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

  {
    "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