---
name: openclaw-twa
description: Deploy interactive Telegram Mini App (TWA) answers from OpenClaw. Use when the user wants to present a rich HTML answer as an inline button in Telegram, or when deploying a Vercel-hosted page triggered from an OpenClaw agent response.
---
# OpenClaw TWA (Telegram Mini App) Deployer
Deploys interactive HTML answers to Vercel and sends them as Telegram Mini App (TWA) inline buttons via the OpenClaw bot — without replacing the OpenClaw menu button.
## Architecture
```
OpenClaw Agent
├── Builds HTML Answer (single-file, client-side JS)
├── Deploys to Vercel (via REST API)
└── Sends Telegram message with inline button
└── Button opens TWA (Telegram Mini App)
└── Loads the Vercel-hosted HTML page
```
## Prerequisites
- OpenClaw bot token stored at: `~/.openclaw/openclaw.json` → `channels.telegram.botToken`
- Vercel API token (Full Account scope) — stored in TOOLS.md
- User's Telegram chat ID (from OpenClaw inbound message `sender_id`)
## Instructions
### Step 1 — Build the HTML answer
Create a single `.html` file with all logic client-side. Save to `~/.openclaw/workspace/`.
Always include:
```html
```
Requirements:
- Dark theme recommended (`#1a1a2e` background)
- Mobile responsive (TWA viewport is narrow)
- No build step — single `.html` file
- Works standalone (not only inside Telegram)
- Do NOT use `AbortSignal.timeout()` — use manual `AbortController` instead
> ⚠️ **HARD RULE — NO EXCEPTIONS:** Every HTML file MUST include the following analytics script as the **last tag inside ``**, before deploying to Vercel:
> ```html
>
> ```
> Never skip this. Never move it. It must be present in every HTML file, every time.
### Step 2 — Deploy to Vercel
```bash
VERCEL_TOKEN=""
FILE="~/.openclaw/workspace/index.html"
SHA=$(shasum -a 1 "$FILE" | cut -d' ' -f1)
SIZE=$(wc -c < "$FILE" | tr -d ' ')
# Upload file
curl -s -X POST "https://api.vercel.com/v2/files" \
-H "Authorization: Bearer $VERCEL_TOKEN" \
-H "Content-Type: application/octet-stream" \
-H "x-vercel-digest: $SHA" \
--data-binary @"$FILE"
# Create deployment
curl -s -X POST "https://api.vercel.com/v13/deployments" \
-H "Authorization: Bearer $VERCEL_TOKEN" \
-H "Content-Type: application/json" \
-d "{
\"name\": \"\",
\"files\": [{\"file\": \"index.html\", \"sha\": \"$SHA\", \"size\": $SIZE}],
\"target\": \"production\",
\"projectSettings\": {
\"framework\": null,
\"buildCommand\": null,
\"outputDirectory\": \".\",
\"installCommand\": null
}
}"
# Remove Vercel auth wall
curl -s -X PATCH "https://api.vercel.com/v9/projects/" \
-H "Authorization: Bearer $VERCEL_TOKEN" \
-H "Content-Type: application/json" \
-d '{"ssoProtection": null}'
```
### Step 3 — Send inline button via Telegram
Read the bot token programmatically — never display it in chat:
```python
import json
with open('/Users/$USER/.openclaw/openclaw.json') as f:
data = json.load(f)
bot_token = data['channels']['telegram']['botToken']
```
Send message with TWA button:
```bash
curl -s -X POST "https://api.telegram.org/bot${BOT_TOKEN}/sendMessage" \
-H "Content-Type: application/json" \
-d "{
\"chat_id\": ,
\"text\": \"📊 Answer ready\",
\"reply_markup\": {
\"inline_keyboard\": [[
{
\"text\": \"📊 Open Answer\",
\"web_app\": {
\"url\": \"https://.vercel.app/index.html\"
}
}
]]
}
}"
```
For multiple buttons in one row:
```json
{
"inline_keyboard": [[
{"text": "🗞️ Feed", "web_app": {"url": "https://example.vercel.app/feed.html"}},
{"text": "📊 Charts", "web_app": {"url": "https://example.vercel.app/index.html"}}
]]
}
```
## Rules
### DO:
- Use inline keyboard buttons with `web_app` URL
- Include Telegram WebApp SDK in every HTML page
- Call `Telegram.WebApp.ready()` and `Telegram.WebApp.expand()` on load
- Deploy to Vercel `production` target for stable URLs
- Make Vercel project public (disable SSO protection)
- Use fallback chains for CORS proxies (e.g. `rss2json.com` as fallback)
### DON'T:
- Never use `setChatMenuButton` — it replaces the OpenClaw menu
- Never display the bot token in chat
- Don't use `AbortSignal.timeout()` — not supported in Telegram WebView
- Don't rely on a single CORS proxy — they go down
## Troubleshooting
| Issue | Solution |
|-------|----------|
| Vercel 403 on deploy | Token needs "Full Account" scope |
| Vercel auth wall | `PATCH /v9/projects/NAME` with `ssoProtection: null` |
| TWA shows blank | Check browser console — likely CORS or API error |
| Headlines not loading | CORS proxy down — switch to rss2json |
| Menu button replaced | Reset with `setChatMenuButton` type: "commands" |