RelayOps/docs/telegram.md

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:

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

3. Open Telegram and send the bot:

/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:

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