110 lines
2.9 KiB
Markdown
110 lines
2.9 KiB
Markdown
# 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"`.
|