Skip to content
SupaCloud Docs
Select themeSelect language

Connect a Telegram bot

The Telegram bot gives you the same control surface as the web terminal — launch tasks, follow live output, manage schedules — from any Telegram client. It boots only when TELEGRAM_BOT_TOKEN is set; the token alone is enough to start taking commands.

Prerequisites

Section titled “Prerequisites”
  • A Telegram bot created via @BotFather and its token.
  • A running SupaCloud instance with network access to api.telegram.org.
  • Your own SupaCloud account (so you can generate a link token in Settings).

Steps

Section titled “Steps”

  1. Set the bot token.

    Add TELEGRAM_BOT_TOKEN to your SupaCloud server environment before starting (or restarting) the server. The bot will not boot if this variable is absent.

    TELEGRAM_BOT_TOKEN=<your-bot-token>

    On a successful connection the server logs:

    Telegram bot started: @<your-bot-username>

  2. Generate a link token in SupaCloud.

    Open Settings in the web UI and go to the Telegram tab. A one-time link token is shown automatically (use Refresh to generate a new one). Copy the token — it expires after a short window.

    Alternatively, call the API directly:

    POST /api/settings/telegram-link-token
    Authorization: Bearer <session-token>

    The response contains token and expires_at.

  3. Link your Telegram account.

    In any Telegram chat with your bot, send:

    /link <token>

    where <token> is the value from the previous step. The bot responds with a confirmation message on success. The token is one-time: once consumed it cannot be reused.

  4. Verify the link.

    Send /status to your bot. It should reply with your active tasks (or an empty list) rather than a “not linked” prompt. If you see the “not linked” message your chat ID is shown — use it to diagnose any whitelist issues.

Verify the connection

Section titled “Verify the connection”
Command Description
/status Active tasks — sends an inline-button list; tap a task for Logs / Cancel / Follow.

After /follow <id> the bot enters live mode, streaming task output as a single edited message; send /unfollow or plain text as an intervention. /run launches a task in the background and replies with its ID — /follow <id> it to watch live output. See Telegram commands for the full command reference and live-mode details.

See also

Section titled “See also”