# Telegram

## What Changed

The repository now includes a working Telegram MVP flow:

- authenticated users can request a one-time Telegram link code;
- the bot completes linking through `/start LINK_CODE`;
- linked users can use `/status` and `/services`;
- linked users with role `admin` or `operator` can use `/restart SERVER_NAME SERVICE_NAME`;
- bot-triggered restart actions are recorded with `actor_source="telegram"`;
- authenticated users can send a test message through `POST /api/v1/telegram/test-message`.

## Configuration

Required environment variables:

- `TELEGRAM_BOT_TOKEN`
- `TELEGRAM_BOT_API_SECRET`
- `TELEGRAM_MODE`
- `TELEGRAM_LINK_CODE_EXPIRE_MINUTES`

Bot runtime variables:

- `BACKEND_API_BASE_URL`
  Default in the bot process is `http://backend:8000/api/v1`

Notes:

- `TELEGRAM_BOT_API_SECRET` must match in both backend and bot environments;
- `TELEGRAM_BOT_TOKEN` must belong to the bot that will receive user commands;
- link codes expire automatically after the configured number of minutes.

## Linking Flow

1. Sign in to the panel or call the API with a valid user token.
2. Request a link code:

```bash
curl -X POST http://localhost:8000/api/v1/telegram/link \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

3. Open Telegram and send the bot:

```text
/start YOUR_LINK_CODE
```

4. After the bot confirms linking, the Telegram account is attached to that internal user.

## Supported Commands

- `/start LINK_CODE`
  Completes Telegram linking.

- `/status`
  Returns the health summary for active servers visible to the linked user.

- `/services`
  Returns managed services across active servers.

- `/services SERVER_NAME`
  Returns managed services for a specific server.

- `/restart SERVER_NAME SERVICE_NAME`
  Queues a restart action for linked users with role `admin` or `operator`.

## API Endpoints

User-facing:

- `GET /api/v1/telegram/status`
- `POST /api/v1/telegram/link`
- `GET /api/v1/telegram/link/me`
- `DELETE /api/v1/telegram/link/{link_id}`
- `POST /api/v1/telegram/test-message`

Bot/internal:

- `POST /api/v1/telegram/bot/link/complete`
- `POST /api/v1/telegram/bot/status`
- `POST /api/v1/telegram/bot/services`
- `POST /api/v1/telegram/bot/restart`

The bot/internal endpoints are protected by `X-Telegram-Bot-Secret`.

## How To Run

For local development:

1. Set `TELEGRAM_BOT_TOKEN` and `TELEGRAM_BOT_API_SECRET` in `.env`.
2. Start the stack:

```bash
docker compose up --build
```

3. Request a link code through the backend API.
4. Complete the link in Telegram with `/start LINK_CODE`.
5. Verify `/status` and `/services`.

## How To Verify

1. `POST /api/v1/telegram/link` returns a `link_code`.
2. `/start LINK_CODE` in Telegram succeeds.
3. `GET /api/v1/telegram/link/me` shows the linked chat.
4. `POST /api/v1/telegram/test-message` returns success.
5. `/restart SERVER_NAME SERVICE_NAME` creates an action and audit entry with `actor_source="telegram"`.