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

# Telegram

> Use your AI assistant via Telegram

Connect your Coral assistant to Telegram so you can chat with it via DMs and group chats.

## Overview

The Telegram integration is **sandbox-native** — your bot token is stored securely inside your isolated sandbox environment and never leaves it. You create a bot through Telegram's BotFather and provide the token to Coral.

## Prerequisites

* A Coral account with an active sandbox
* A Telegram account

## Step 1: Create a Bot with BotFather

1. Open Telegram and search for [@BotFather](https://t.me/BotFather), or click the link to open it directly.
2. Send the `/newbot` command.
3. Follow the prompts:
   * Enter a **display name** for your bot (e.g., "My AI Assistant").
   * Enter a **username** for your bot. It must end in `bot` (e.g., `my_coral_assistant_bot`).
4. BotFather will reply with your **bot token**. It looks like `123456789:ABCdefGHIjklMNOpqrSTUvwxYZ`. Copy it.

<Warning>
  Keep your bot token private. Anyone with the token can control your bot. If you suspect it has been leaked, use `/revoke` with BotFather to generate a new token.
</Warning>

## Step 2: Configure Privacy Settings (Optional)

By default, Telegram bots can only see messages that directly mention them or are replies to their messages in group chats. If you want your bot to see all messages in a group:

1. Open a chat with [@BotFather](https://t.me/BotFather).
2. Send `/setprivacy`.
3. Select your bot.
4. Choose **"Disable"** to allow the bot to read all group messages.

<Note>
  This is only needed for group chats. In direct messages, the bot always sees all messages.
</Note>

## Step 3: Connect in Coral

1. Open the [Coral dashboard](https://app.coral.inc) and go to the **Integrations** page.
2. Click on the **Telegram** card.
3. Paste your bot token into the **Bot Token** field.
4. Click **"Connect"**.

Coral validates your token against the Telegram Bot API (`/getMe`), then applies the configuration to your sandbox.

## Step 4: Pair Your Telegram Account

After the bot connects, you need to pair your Telegram account:

1. Open Telegram and search for your bot by its username (e.g., `@my_coral_assistant_bot`).
2. Send it any message (e.g., "Hello").
3. The bot will reply with an **8-character pairing code** (e.g., `KVM9A75Y`).
4. Go back to the Coral Integrations page and paste the code into the **Pairing Code** field.
5. Click **"Approve"**.

<Note>
  You can skip pairing and do it later, but the bot will not respond to your messages until pairing is completed.
</Note>

## Managing Your Telegram Integration

Once connected, the Telegram card on the Integrations page shows your bot's status:

* **Connected** — The bot is online and responsive.
* **Configured but not connected** — The token is saved but the bot cannot connect. Click **"Reconfigure"** to enter a new token.

To disconnect, click **"Disconnect"** on the integration card. This removes the bot token from your sandbox.

## Troubleshooting

| Problem                                  | Solution                                                                                                |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Bot shows "configured but not connected" | Your token may have been revoked. Use `/revoke` with BotFather to generate a new token and reconfigure. |
| Bot doesn't respond in group chats       | Make sure you disabled privacy mode via `/setprivacy` with BotFather.                                   |
| Bot doesn't respond to DMs               | Ensure pairing is completed. Also verify the token is correct.                                          |
| "Invalid bot token" error                | Ensure you copied the full token from BotFather. The format is `123456789:ABCdefGHIjklMNOpqrSTUvwxYZ`.  |

## Security

* Your bot token is stored exclusively inside your sandbox's configuration file (`~/.openclaw/openclaw.json`).
* The token never passes through Coral's servers — it is sent directly from the Coral UI to your sandbox via an authenticated gateway RPC.
* If you back up and restore your sandbox, the Telegram configuration is preserved in the backup.