Skip to main content
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, 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.
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.

​
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.
  2. Send /setprivacy.
  3. Select your bot.
  4. Choose “Disable” to allow the bot to read all group messages.
This is only needed for group chats. In direct messages, the bot always sees all messages.

​
Step 3: Connect in Coral

  1. Open the Coral dashboard 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”.
You can skip pairing and do it later, but the bot will not respond to your messages until pairing is completed.

​
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

ProblemSolution
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 chatsMake sure you disabled privacy mode via /setprivacy with BotFather.
Bot doesn’t respond to DMsEnsure pairing is completed. Also verify the token is correct.
”Invalid bot token” errorEnsure 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.