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

# Telegram setup

Create the bot in BotFather, give OpenClaw its token, approve the first DM, and add the bot to a group.

## Quick setup

**1. Create the bot token in BotFather**

Both flows end with a token you paste into OpenClaw — pick one:

* **Chat flow**: open Telegram and chat with **@BotFather**. Confirm the handle is exactly `@BotFather`. Run `/newbot`, follow the prompts, and save the token.
* **Web flow**: open [BotFather's web app](https://t.me/BotFather?startapp). It runs in every Telegram client, including [web.telegram.org](https://web.telegram.org). Create the bot in the UI, then copy its token.

**2. Configure token and DM policy**

The fastest option is the CLI. It writes the token into your config for you:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw channels add --channel telegram --token <bot-token>
```

To edit config by hand instead, put this in `~/.openclaw/openclaw.json`:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } },
    },
  },
}
```

Env fallback: `TELEGRAM_BOT_TOKEN` (default account only). Named accounts must use `botToken` or `tokenFile`.
Telegram does **not** use `openclaw channels login telegram`. Set the token in config or env, then start the gateway.

**3. Verify the channel**

With the default [hot reload](https://docs2.openclaw.ai/gateway/configuration/hot-reload.md), the running
Gateway applies the new channel configuration. Check that Telegram is ready:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw channels status --probe
```

If the Gateway is offline, start it with `openclaw gateway start` for a managed
service, or `openclaw gateway` to run it in this terminal. If you changed the
service environment, restart the Gateway to load it.

**4. Approve your first DM**

Open Telegram and send any message to your bot. That message creates the
pairing request the next command lists:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>
```

Pairing codes expire after 1 hour.

**5. Add the bot to a group**

Add the bot to your group, then get the two IDs group access needs:

* your Telegram user ID, for `allowFrom` / `groupAllowFrom`
* the Telegram group chat ID, as the key under `channels.telegram.groups`

Get the group chat ID from `openclaw logs --follow`, a forwarded-ID bot, or Bot API `getUpdates`. After the group is allowed, `/whoami@<bot_username>` confirms the user and group IDs.

Negative supergroup IDs starting with `-100` are group chat IDs. They go under `channels.telegram.groups`, not `groupAllowFrom`.

> [!NOTE]
>
> Token resolution is account-aware. `tokenFile` beats `botToken`, and `botToken` beats env. Config always wins over `TELEGRAM_BOT_TOKEN`, which only resolves for the default account. After a successful startup, OpenClaw caches the bot identity for up to 24 hours, so restarts skip an extra `getMe` call. Changing or removing the token clears that cache.

## Telegram side settings

> **Privacy mode and group visibility**
>
> Telegram bots default to **Privacy Mode**, which limits which group messages they receive.
>
> To see all group messages, either:
>
> * disable privacy mode via `/setprivacy`, or
> * make the bot a group admin.
>
> After toggling privacy mode, remove and re-add the bot in each group so Telegram applies the change.

> **Group permissions**
>
> Admin status is controlled in Telegram group settings. Admin bots receive all group messages, useful for always-on group behavior.

> **Helpful BotFather toggles**
>
> * `/setjoingroups` — allow/deny group adds
> * `/setprivacy` — group visibility behavior
>
> The same settings are available in [BotFather's web app](https://t.me/BotFather?startapp) if you prefer a UI over chat commands.