Telegram Bot in a Cage

This guide walks through deploying a Telegram bot inside a LobsterCage, with automatic wake-on-message via the webhook gateway.

Prerequisites

A LobsterCage account (sign up )
The lobster CLI installed (npm install -g lobstercage-cli)
A Telegram bot token from @BotFather

1. Create a cage


lobster deploy telegram-bot

2. Set the bot token


lobster env set telegram-bot BOT_TOKEN=your-telegram-bot-token

3. Get the webhook URL


lobster status telegram-bot

Copy the Webhook URL from the output. It looks like:


https://gateway.lobstercage.ai/hook/{cageId}/{token}

4. Install OpenClaw in the cage

SSH into the cage and install OpenClaw , the agent framework that handles Telegram integration:


lobster ssh telegram-bot

Inside the cage:


cd /workspace
# Install OpenClaw or your preferred bot framework
npm init -y
npm install openclaw

5. Register the webhook with Telegram

Use the Telegram Bot API to point your bot at the cage’s webhook URL:


curl -X POST "https://api.telegram.org/bot${BOT_TOKEN}/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://gateway.lobstercage.ai/hook/{cageId}/{token}"}'

Replace the URL with your actual webhook URL from step 3.

6. How it works in production

A user sends a message to your Telegram bot
Telegram POSTs the update to your cage’s webhook URL
If the cage is running — the request is forwarded immediately
If the cage is hibernated:
- The gateway buffers the request (encrypted)
- Returns a Telegram-compatible response
- Wakes the cage asynchronously
- Drains buffered messages in order once healthy

The cage automatically hibernates after 30 minutes of inactivity, keeping costs near zero when the bot isn’t in use.

Tips

Startup time: Cages typically wake in 10–30 seconds. Telegram is tolerant of short delays.
Multiple bots: You can run multiple bots in one cage — they all share the same webhook URL with different paths.
Logs: Use lobster tail telegram-bot to watch logs in real time.