integrate telegram bot

dev/post-phase/refinement/RUNBOOK.md

@@ -164,6 +164,37 @@ Prove search works without the frontend: open Swagger →
    `GET /api/v1/me` all return **200** with the `ApiResult` envelope, and there is **no CORS error** in the
    console. That is the first real authenticated request between the two projects.
 
+### OTP over Telegram (optional — instead of reading the log)
+
+For manual testing you can have the code arrive **on your phone in Telegram** rather than in the server
+console. A standalone dev-only relay ([`telegram-otp-bot/`](../../../telegram-otp-bot/README.md)) forwards it;
+the API talks to it through the normal `ISmsSender` seam. **Development only** — the relay *broadcasts* every
+code to every configured chat id, so it is a test-group convenience, not an SMS gateway.
+
+1. **Start the relay** (see its README for creating the bot with @BotFather and discovering chat ids —
+   each recipient must press **Start** in Telegram first, then `GET /chat_ids`):
+   ```bash
+   cd telegram-otp-bot && npm start      # no npm install — zero dependencies
+   ```
+   `api.telegram.org` is filtered in Iran, so set `TELEGRAM_PROXY_URL` in its `.env` to your VPN/proxy
+   client (`http://127.0.0.1:10809`, `socks5://…`, or the proxy container on a VPS). The boot banner prints
+   the bot's `@username` — that line appearing means the token *and* the proxy work.
+2. **Share the secret with the API** — the same value on both sides (relay `.env` `API_KEY`, API user-secret):
+   ```bash
+   cd server/src/API/Baya.Web.Api
+   dotnet user-secrets set "Seams:Sms:Telegram:ApiKey" "<the relay's API_KEY>"
+   ```
+3. **Flip the provider** in `server/src/API/Baya.Web.Api/appsettings.Development.json`:
+   ```jsonc
+   "Seams": { "Sms": { "Provider": "telegram" } }   // committed default is "mock"
+   ```
+4. **Log in** as usual — the 6-digit code arrives in Telegram. The `dev/last_otp` helper keeps working
+   alongside it (`telegram` is the one non-mock provider that leaves the capture bridge on), so scripts and
+   e2e tests are unaffected. Set the provider back to `mock` to return to reading the console.
+
+If the relay is down or reaches nobody it answers `502` and **login fails loudly** (`request_otp` returns an
+error) rather than pretending an undelivered code was sent.
+
 ---
 
 ## Good to know