> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suji.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# Telegram

> Connect a Telegram bot to your Suji instance.

Connecting Telegram to OpenClaw lets your bot receive and respond to messages on Telegram. Once connected, anyone who messages the bot is talking to your OpenClaw agent — in direct messages and in group chats.

## What you'll need

* A Telegram account (any free account works).
* The Telegram app on your phone/desktop, or [Telegram Web](https://web.telegram.org).
* A running [OpenClaw install](/marketplace/openclaw) on a Suji VM.

## Create a Telegram Bot

Every Telegram bot is created through **BotFather**, Telegram's official tool for registering and managing bots. You'll chat with BotFather like a normal Telegram conversation.

<Steps>
  <Step title="Open BotFather">
    Open Telegram and search for `@BotFather` in the search bar, or click this link directly: [@BotFather](https://t.me/BotFather).

    BotFather is verified by Telegram and has a blue checkmark next to its name. Make sure you're messaging the real BotFather and not an impersonator.
  </Step>

  <Step title="Start a conversation">
    Click **Start** (or type `/start`) to begin interacting with BotFather. It will reply with a list of available commands.
  </Step>

  <Step title="Create a new bot">
    Type `/newbot` and send it. BotFather will ask you two things:

    1. **A display name for your bot** — This is the name users see in chats. It can be anything, like `My Store Assistant` or `Acme Support Bot`. You can change this later.

    2. **A username for your bot** — This is the unique `@username` that people use to find your bot. It **must** end in `bot` (for example: `my_store_bot`, `AcmeSupportBot`, or `acme_help_bot`). Usernames are case-insensitive and cannot be changed after creation.

    <Tip>
      If the username you want is taken, try adding a prefix or suffix. For example, if `support_bot` is taken, try `acme_support_bot` or `support_bot_123`.
    </Tip>
  </Step>

  <Step title="Copy the bot token">
    After you choose a valid username, BotFather will reply with a congratulations message that includes your **bot token**. It looks something like this:

    ```
    123456789:ABCdefGHIjklMNOpqrSTUvwxYZ1234567890
    ```

    The token is made up of two parts separated by a colon: a numeric bot ID and an alphanumeric secret string. Copy the entire token — you'll paste it into Suji in the next section.

    <Warning>
      **Keep your bot token secret.** Anyone who has your token can fully control your bot — read messages, send messages, and change settings. Never share it publicly or commit it to a code repository.
    </Warning>
  </Step>

  <Step title="Configure privacy mode (for group chats)">
    By default, Telegram bots in group chats can only see messages that are either directed at them (using `/commands`) or replies to their messages. This is called **privacy mode**, and it's enabled by default.

    If you want your bot to read and respond to **all messages** in a group chat (not just commands and replies), you need to disable privacy mode:

    1. Send `/setprivacy` to BotFather
    2. Select your bot from the list
    3. Choose **Disable**

    BotFather will confirm that privacy mode has been disabled.

    <Note>
      If your bot will only be used in direct messages (one-on-one chats), you can skip this step. Privacy mode only affects group chat behavior.
    </Note>

    <Tip>
      After changing the privacy mode, you need to **remove and re-add** the bot to any existing group chats for the change to take effect. New groups added after the change will work automatically.
    </Tip>
  </Step>
</Steps>

## Connect it to OpenClaw

You can wire the token up at two points:

### During install

In the OpenClaw install form, tick **Telegram** in the **Channels** multiselect and paste your bot token into the **Telegram bot token** field. Click **Deploy** — OpenClaw connects to Telegram on first boot.

### After install

If you didn't add Telegram at install time, open the OpenClaw install detail page → **Edit Install** → tick **Telegram** → paste the token → **Save**. Suji redeploys OpenClaw with the new env. Existing channels keep working through the redeploy.

## Verify

1. Open Telegram and search for your bot by `@username`.
2. Click **Start** or type `/start`.
3. Send any message — your OpenClaw agent should reply.

If it doesn't reply, see the troubleshooting block below.

<Tip>
  Make sure OpenClaw has finished its [first-connection setup](/marketplace/openclaw#first-connection-two-extra-steps) (tokenized URL + device pairing) so the Control UI is reachable. An unconfigured agent may not behave as expected.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Bot not responding to messages">
    Check, in order:

    * **VM and install are running.** Dashboard → instance must be `running`; the OpenClaw install must also be `running`.
    * **You started the bot.** Telegram requires the user to press **Start** (or send `/start`) before the bot can send messages.
    * **Token is exactly right.** Even a stray space invalidates it. Re-copy from BotFather.
    * **Install logs.** Dashboard → Logs → pick OpenClaw → look for `[telegram]` lines around the time you sent the message. If you don't see any, the token never authenticated.
  </Accordion>

  <Accordion title="Token is invalid / revoked">
    1. Open [@BotFather](https://t.me/BotFather) → `/mybot` → select your bot. Confirm it exists.
    2. If you need a fresh token, send `/token` (gets the current one) or `/revoke` (revokes + regenerates). Revoking takes effect immediately.
    3. In Suji: install detail page → **Edit Install** → paste the new Telegram token → **Save**.
  </Accordion>

  <Accordion title="Messages are delayed">
    Some delay is expected — OpenClaw queues the message and waits on the AI provider. If it's consistently slow:

    * **Resource pressure** — Metrics tab shows CPU/memory near the cap; [resize](/manage-vm/resize) the VM up.
    * **AI provider latency** — the upstream LLM is the slow path; try a faster model.
    * **Complex prompts** — long system prompts and tool use add round trips.
  </Accordion>

  <Accordion title="Bot doesn't respond in group chats">
    If your bot works in direct messages but ignores messages in group chats, **privacy mode** is likely still enabled. By default, bots in groups can only see commands (messages starting with `/`) and direct replies to the bot.

    To fix this:

    1. Send `/setprivacy` to [@BotFather](https://t.me/BotFather)
    2. Select your bot
    3. Choose **Disable**
    4. **Remove the bot from the group** and **re-add it** — this step is required for the change to take effect in existing groups

    After re-adding the bot, it should be able to see and respond to all messages in the group.
  </Accordion>
</AccordionGroup>