From 69299c055f9baffd366434ac25949a696aba0e04 Mon Sep 17 00:00:00 2001
From: "alexei.dolgolyov" <dolgolyov.alexei@gmail.com>
Date: Thu, 19 Mar 2026 18:05:12 +0300
Subject: [PATCH] Add Phase 10 plan: Telegram bot commands

15 commands across 4 categories:
- Informational: /status, /albums, /events
- On-demand: /summary, /latest, /memory, /random
- Asset browsing: /search, /favorites, /people
- Management: /trackers, /targets, /help

Auto-registers commands with Telegram setMyCommands API when
config changes. Per-bot command enable/disable in UI.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 plans/phase-10-telegram-commands.md | 77 +++++++++++++++++++++++++++++
 1 file changed, 77 insertions(+)
 create mode 100644 plans/phase-10-telegram-commands.md

diff --git a/plans/phase-10-telegram-commands.md b/plans/phase-10-telegram-commands.md
new file mode 100644
index 0000000..cde2b54
--- /dev/null
+++ b/plans/phase-10-telegram-commands.md
@@ -0,0 +1,77 @@
+# 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]` — Show latest assets from an album (or all)
+- `/memory` — Trigger "On This Day" memory notification now
+- `/random [album]` — Send random photo(s) from an album
+
+### Asset Browsing
+- `/search <query>` — Search assets by filename, people, location
+- `/favorites [album]` — Show favorite assets
+- `/people` — List detected people across albums
+
+### Management
+- `/trackers` — List trackers with enable/disable toggle (inline buttons)
+- `/targets` — List notification targets
+- `/help` — Show available commands with descriptions
+
+---
+
+## Tasks
+
+### 1. Command registry model `[ ]`
+- New entity or config: list of enabled commands per bot
+- Admin can enable/disable individual commands per bot
+- Default set of commands enabled on bot registration
+
+### 2. Auto-register commands with Telegram `[ ]`
+- Call `setMyCommands` API when commands config changes
+- Call on bot creation and on config update
+- Store command descriptions in i18n (EN/RU based on bot locale setting)
+
+### 3. Webhook command handler `[ ]`
+- Extend existing webhook handler to route `/command` messages
+- Parse command + arguments
+- Execute corresponding logic (reuse existing services)
+- Return formatted response
+
+### 4. Implement each command `[ ]`
+- `/status`, `/albums`, `/events` — read from DB
+- `/summary`, `/memory`, `/latest`, `/random` — call watcher/notifier services
+- `/search`, `/favorites`, `/people` — call Immich API via core client
+- `/trackers`, `/targets` — read from DB, optional inline keyboard for toggle
+- `/help` — auto-generated from enabled commands
+
+### 5. Frontend: command config per bot `[ ]`
+- On telegram-bots page, expandable "Commands" section per bot
+- Checkboxes to enable/disable each command
+- Bot locale selector (for command descriptions language)
+- "Sync Commands" button (calls setMyCommands)
+
+---
+
+## Acceptance Criteria
+
+- [ ] Commands registered with Telegram and visible in bot menu
+- [ ] Each command returns a useful response
+- [ ] Commands auto-sync when config changes
+- [ ] Admin can enable/disable commands per bot via UI