Telegram Bot Setup

LobsterCage’s webhook gateway handles Telegram bot webhooks with automatic buffering during hibernation and wake-on-message.

How it works

1. Deploy a cage and note its webhook URL
2. Register the webhook URL with Telegram
3. OpenClaw listens on port 18789 inside the cage
4. The gateway proxy handles forwarding, buffering during hibernation, and wake-on-message

Telegram webhook setup

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

The simplest path is to let OpenClaw register the webhook for you during openclaw configure. To register manually:

curl -X POST "https://api.telegram.org/bot${BOT_TOKEN}/setWebhook" \
  -d '{"url": "YOUR_WEBHOOK_URL"}'

Telegram sends JSON updates for messages, callbacks, and inline queries. See the full Telegram bot guide.

Hibernation behavior

When a Telegram message arrives while your cage is hibernated:

1. The gateway proxy buffers the message (encrypted at rest)
2. Returns a playful “waking up” response to the user
3. Wakes the cage (~10-30 seconds)
4. Delivers the buffered message to OpenClaw
5. OpenClaw processes and responds normally

Users see a brief “waking up” message, then the real response arrives.

Programmatic setup

For creating Telegram bots programmatically:

lobster create my-bot --template openclaw-chatbot
lobster env set my-bot ANTHROPIC_API_KEY=sk-ant-...
lobster env set my-bot TELEGRAM_BOT_TOKEN=123456:ABC...

The openclaw-chatbot template auto-detects the Telegram bot token and generates the OpenClaw config at boot.

Common considerations

• Buffering: When a cage is hibernated, incoming webhooks are encrypted and buffered for up to 1 hour while the cage wakes
• Rate limits: 30 requests/min per cage, 60 requests/min per IP
• Payload size: Max 1 MB per request
• Port: OpenClaw listens on port 18789 inside the cage