` — adapts automatically to user theme.
---
## 10. MarkdownV2 Escaping
Telegram's MarkdownV2 requires escaping special characters. Get this wrong and your messages fail silently or look broken.
### Characters That Must Be Escaped
```
_ * [ ] ( ) ~ ` > # + - = | { } . !
```
### Escape Function
```ts
// src/lib/telegram-utils.ts
/**
* Escape a string for Telegram MarkdownV2.
* Use this for ANY user-generated or dynamic text inserted into MarkdownV2 messages.
*/
export function escapeMarkdownV2(text: string): string {
return text.replace(/([_*\[\]()~`>#+\-=|{}.!\\])/g, "\\$1");
}
/**
* Escape text for use inside a MarkdownV2 code block (`` ` `` or ``` ``` ```).
* Only ` and \ need escaping inside code blocks.
*/
export function escapeMarkdownV2Code(text: string): string {
return text.replace(/([`\\])/g, "\\$1");
}
/**
* Escape text for use inside a MarkdownV2 link URL.
* Only ) and \ need escaping inside (...) of links.
*/
export function escapeMarkdownV2Url(url: string): string {
return url.replace(/([)\\])/g, "\\$1");
}
// --- Usage examples ---
// Simple message with dynamic content
const username = "John_Doe";
const msg = `Hello, *${escapeMarkdownV2(username)}*\\!`;
// Result: "Hello, *John\_Doe*\!"
// Link with dynamic URL
const title = "My Page (v2)";
const url = "https://example.com/page?a=1&b=2";
const linkMsg = `[${escapeMarkdownV2(title)}](${escapeMarkdownV2Url(url)})`;
// Code block
const code = "const x = `hello`";
const codeMsg = `\`\`\`js\n${escapeMarkdownV2Code(code)}\n\`\`\``;
```
### Common Patterns
```ts
// Bold text with dynamic content
`*${escapeMarkdownV2(product.title)}*`
// Italic
`_${escapeMarkdownV2(text)}_`
// Strikethrough
`~${escapeMarkdownV2(text)}~`
// Inline code
`\`${escapeMarkdownV2Code(text)}\``
// Spoiler
`||${escapeMarkdownV2(text)}||`
// ⚠️ WRONG — will break if text contains special chars:
`*${product.title}*`
// ✅ CORRECT:
`*${escapeMarkdownV2(product.title)}*`
```
---
## 11. Database Options
### Development: SQLite (local file)
```bash
npm install @libsql/client
```
### Production: Turso (distributed SQLite at the edge)
```bash
# Install Turso CLI
curl -sSfL https://get.tur.so/install.sh | bash
# Create a database
turso db create my-miniapp
turso db show my-miniapp --url # get the URL
turso db tokens create my-miniapp # get auth token
```
### Unified Database Client
```ts
// src/lib/database.ts
import { createClient, type Client } from "@libsql/client";
let _db: Client | null = null;
export function getDb(): Client {
if (_db) return _db;
const isProduction = process.env.NODE_ENV === "production";
if (isProduction && process.env.TURSO_DATABASE_URL) {
_db = createClient({
url: process.env.TURSO_DATABASE_URL,
authToken: process.env.TURSO_AUTH_TOKEN,
});
} else {
// Local SQLite file for development
_db = createClient({
url: process.env.DATABASE_URL || "file:local.db",
});
}
return _db;
}
export const db = getDb();
// Run migrations on startup
export async function migrate() {
await db.executeMultiple(`
CREATE TABLE IF NOT EXISTS users (
id INTEGER PRIMARY KEY AUTOINCREMENT,
telegram_id INTEGER UNIQUE NOT NULL,
username TEXT,
first_name TEXT,
credits INTEGER DEFAULT 0,
created_at TEXT DEFAULT (datetime('now')),
updated_at TEXT DEFAULT (datetime('now'))
);
CREATE TABLE IF NOT EXISTS payments (
id INTEGER PRIMARY KEY AUTOINCREMENT,
user_id INTEGER NOT NULL,
product_id TEXT NOT NULL,
amount INTEGER NOT NULL,
telegram_charge_id TEXT UNIQUE NOT NULL,
provider_charge_id TEXT,
status TEXT DEFAULT 'completed',
created_at TEXT DEFAULT (datetime('now'))
);
CREATE TABLE IF NOT EXISTS subscriptions (
id INTEGER PRIMARY KEY AUTOINCREMENT,
user_id INTEGER NOT NULL,
plan TEXT NOT NULL,
expires_at TEXT NOT NULL,
created_at TEXT DEFAULT (datetime('now')),
UNIQUE(user_id, plan)
);
CREATE INDEX IF NOT EXISTS idx_users_telegram_id ON users(telegram_id);
CREATE INDEX IF NOT EXISTS idx_payments_user_id ON payments(user_id);
CREATE INDEX IF NOT EXISTS idx_payments_charge_id ON payments(telegram_charge_id);
CREATE INDEX IF NOT EXISTS idx_subscriptions_user_id ON subscriptions(user_id);
`);
}
```
### Using the Database
```ts
// Upsert user on first visit
export async function ensureUser(
telegramId: number,
username?: string,
firstName?: string
) {
await db.execute({
sql: `INSERT INTO users (telegram_id, username, first_name)
VALUES (?, ?, ?)
ON CONFLICT (telegram_id) DO UPDATE SET
username = COALESCE(excluded.username, users.username),
first_name = COALESCE(excluded.first_name, users.first_name),
updated_at = datetime('now')`,
args: [telegramId, username || null, firstName || null],
});
}
// Check subscription
export async function hasActiveSubscription(
telegramId: number
): Promise
{
const result = await db.execute({
sql: `SELECT 1 FROM subscriptions
WHERE user_id = ? AND expires_at > datetime('now')
LIMIT 1`,
args: [telegramId],
});
return result.rows.length > 0;
}
// Get user credits
export async function getUserCredits(telegramId: number): Promise {
const result = await db.execute({
sql: `SELECT credits FROM users WHERE telegram_id = ?`,
args: [telegramId],
});
return (result.rows[0]?.credits as number) ?? 0;
}
```
---
## 12. Next.js Deployment
### Project Structure
```
my-miniapp/
├── src/
│ ├── app/
│ │ ├── api/
│ │ │ ├── bot/route.ts # Webhook endpoint
│ │ │ ├── purchase/route.ts # Stars purchase trigger
│ │ │ └── profile/route.ts # User profile
│ │ ├── globals.css
│ │ ├── layout.tsx
│ │ ├── page.tsx
│ │ └── providers.tsx # TelegramProvider
│ ├── components/
│ │ ├── BuyButton.tsx
│ │ └── ProductCard.tsx
│ ├── hooks/
│ │ └── useTelegramUser.ts
│ └── lib/
│ ├── api.ts # Frontend API client
│ ├── auth-middleware.ts # initData validation middleware
│ ├── bot.ts # grammY bot instance
│ ├── database.ts # SQLite/Turso client
│ ├── payments.ts # Stars payment logic
│ ├── telegram-utils.ts # MarkdownV2 helpers
│ └── validate-init-data.ts # HMAC validation
├── scripts/
│ └── set-webhook.ts
├── .env.local
├── next.config.ts
├── package.json
└── tsconfig.json
```
### next.config.ts
```ts
// next.config.ts
import type { NextConfig } from "next";
const nextConfig: NextConfig = {
// Security headers
async headers() {
return [
{
source: "/(.*)",
headers: [
// X-Frame-Options ALLOW-FROM is deprecated and ignored by modern browsers.
// Use Content-Security-Policy frame-ancestors instead (below).
{
key: "Content-Security-Policy",
value:
"frame-ancestors 'self' https://web.telegram.org https://*.telegram.org",
},
],
},
];
},
};
export default nextConfig;
```
### Root Layout
```tsx
// src/app/layout.tsx
import type { Metadata, Viewport } from "next";
import { TelegramProvider } from "./providers";
import "./globals.css";
export const metadata: Metadata = {
title: "My Mini App",
description: "A Telegram Mini App",
};
export const viewport: Viewport = {
width: "device-width",
initialScale: 1,
maximumScale: 1,
userScalable: false, // Prevent zoom in Mini App
};
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
{/* Telegram Web App script — REQUIRED */}
{children}
);
}
```
### Deploy to Vercel
```bash
# Install Vercel CLI
npm i -g vercel
# Deploy
vercel
# Set environment variables
vercel env add BOT_TOKEN
vercel env add MINI_APP_URL
vercel env add WEBHOOK_URL
vercel env add WEBHOOK_SECRET
vercel env add TURSO_DATABASE_URL
vercel env add TURSO_AUTH_TOKEN
# Deploy to production
vercel --prod
# Set webhook after deployment
WEBHOOK_URL=https://your-app.vercel.app/api/bot npx tsx scripts/set-webhook.ts
```
### Configure in BotFather
1. Message @BotFather
2. `/setmenubutton` → select your bot → enter your Mini App URL
3. Or `/newapp` to create a named Mini App (accessible via `t.me/YourBot/appname`)
---
## 13. Security Hardening
### Checklist
- [x] **Validate initData HMAC on every API request** — never trust client-side data
- [x] **Verify webhook secret header** — prevents forged webhook calls
- [x] **Check auth_date freshness** — reject stale initData (24h max)
- [x] **Use timing-safe comparison** — prevents timing attacks on HMAC
- [x] **Sanitize all inputs** — never trust user data in SQL or messages
- [x] **Rate limit with a shared store** — never an in-memory `Map` on serverless (see below)
- [x] **Treat CloudStorage as client-controlled** — entitlements live server-side, never in CloudStorage
- [x] **Biometry is not auth** — server trust comes only from validated initData
- [x] **Log payment events** — audit trail for disputes; reconcile with `getStarTransactions`
### Webhook Secret Validation
Already shown in the webhook route above. The secret is set via `setWebhook` API and sent by Telegram in the `X-Telegram-Bot-Api-Secret-Token` header.
### Input Sanitization
```ts
// src/lib/sanitize.ts
/**
* Validate and sanitize a product ID.
* Only allow alphanumeric + underscores.
*/
export function sanitizeProductId(input: unknown): string | null {
if (typeof input !== "string") return null;
if (input.length > 64) return null;
if (!/^[a-zA-Z0-9_]+$/.test(input)) return null;
return input;
}
/**
* Validate a Telegram user ID.
*/
export function sanitizeUserId(input: unknown): number | null {
const num =
typeof input === "number" ? input : parseInt(String(input), 10);
if (!Number.isInteger(num) || num <= 0 || num > 2 ** 52) return null;
return num;
}
/**
* Sanitize text for display (strip control characters).
*/
export function sanitizeText(input: string, maxLength = 500): string {
return input
.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, "") // strip control chars
.slice(0, maxLength)
.trim();
}
```
### Rate Limiting (serverless-safe)
> **Do not ship an in-memory `Map` rate limiter to Vercel/Cloudflare/any multi-instance deploy.** Each serverless invocation may run in a fresh isolate, so the counter resets between requests and across regions — attackers fan out and the limit never trips. The `setInterval` cleanup also won't run on serverless. Use a shared store (Upstash Redis, Vercel KV, Cloudflare Durable Object / Rate Limiting binding, or your DB).
**Recommended — Upstash Redis sliding window** (works on Vercel/Edge/Node, free tier available):
```bash
npm install @upstash/ratelimit @upstash/redis
```
```ts
// src/lib/rate-limit.ts
import { Ratelimit } from "@upstash/ratelimit";
import { Redis } from "@upstash/redis";
// Reads UPSTASH_REDIS_REST_URL / UPSTASH_REDIS_REST_TOKEN from env.
const redis = Redis.fromEnv();
const limiter = new Ratelimit({
redis,
limiter: Ratelimit.slidingWindow(30, "60 s"), // 30 req / 60s per key
analytics: true,
prefix: "miniapp:rl",
});
/** Returns true if the caller is OVER the limit (i.e. should be blocked). */
export async function isRateLimited(key: string): Promise {
const { success } = await limiter.limit(key);
return !success;
}
```
Use it in the auth middleware, keyed by the validated user id (so it survives IP rotation):
```ts
// inside withTelegramAuth, after validation succeeds:
if (await isRateLimited(`u:${result.data.user.id}`)) {
return NextResponse.json({ error: "Too many requests" }, { status: 429 });
}
```
**Vercel KV alternative** (same shape — Upstash-compatible):
```ts
import { kv } from "@vercel/kv";
import { Ratelimit } from "@upstash/ratelimit";
const limiter = new Ratelimit({ redis: kv, limiter: Ratelimit.slidingWindow(30, "60 s") });
```
> For a **single long-lived Node process** (a VPS, not serverless) the in-memory `Map` approach is acceptable, but gate it behind an explicit `process.env.RATE_LIMIT_BACKEND === "memory"` flag and keep the cleanup `setInterval` — never make it the default for a Vercel deploy.
### Never Expose Bot Token
```ts
// ❌ WRONG — bot token in client-side code
const BOT_TOKEN = ""; // NEVER hardcode or ship to the client
// ✅ CORRECT — only in server-side code / env vars
// .env.local (never committed to git)
// BOT_TOKEN=
// In API routes (server-side only):
const BOT_TOKEN = process.env.BOT_TOKEN!;
```
---
## 14. Complete Example App
### package.json
> Version ranges below are the **mid-2026 tested set** (see the matrix at the top). Run `npm outdated` and check each package's releases page before pinning — Telegram's SDK and Bot API move quickly.
```json
{
"name": "telegram-miniapp",
"private": true,
"engines": {
"node": ">=20"
},
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start",
"set-webhook": "tsx scripts/set-webhook.ts",
"migrate": "tsx scripts/migrate.ts"
},
"dependencies": {
"@libsql/client": "^0.15.0",
"@telegram-apps/sdk": "^3.0.0",
"@telegram-apps/sdk-react": "^3.0.0",
"@upstash/ratelimit": "^2.0.0",
"@upstash/redis": "^1.34.0",
"grammy": "^1.30.0",
"next": "^15.0.0",
"react": "^19.0.0",
"react-dom": "^19.0.0"
},
"devDependencies": {
"@types/node": "^22.0.0",
"@types/react": "^19.0.0",
"tsx": "^4.19.0",
"typescript": "^5.6.0"
}
}
```
### Main Page
```tsx
// src/app/page.tsx
"use client";
import { useTelegramUser } from "@/hooks/useTelegramUser";
import { BuyButton } from "@/components/BuyButton";
export default function Home() {
const user = useTelegramUser();
if (!user) {
return (
);
}
return (
Welcome, {user.firstName}!
{user.isPremium ? "⭐ Premium user" : "Free user"}
Premium Access
Unlock all features for 7 days.
100 Credits
Top up your credit balance.
);
}
```
### Migration Script
```ts
// scripts/migrate.ts
import { migrate } from "../src/lib/database";
migrate()
.then(() => {
console.log("Migration complete");
process.exit(0);
})
.catch((err) => {
console.error("Migration failed:", err);
process.exit(1);
});
```
---
## 15. Troubleshooting
### Common Issues
| Problem | Cause | Fix |
|---------|-------|-----|
| `hash` validation fails | URL-decoding mismatch | Use raw query string, don't decode before validation |
| Payment never arrives | `pre_checkout_query` not answered in 10s | Ensure handler is fast; avoid DB calls before answering |
| Mini App blank white screen | CSP blocking frame | Add `frame-ancestors` header for telegram.org |
| Theme variables undefined | SDK not initialized / bindCssVars not called | Call `init()`, then `themeParams.bindCssVars()` in the provider |
| Bot commands not working | Webhook not set or wrong URL | Run `set-webhook.ts` and check `getWebhookInfo` |
| `sendInvoice` error 400 | Wrong currency or missing fields | Must use `"XTR"`, empty `provider_token`, integer amount |
| `sendInvoice` 403 "can't initiate conversation" | User never started the bot; `chatId`≠open chat | Use the `openInvoice` link flow instead, or prompt the user to `/start` first |
| MarkdownV2 parse error | Unescaped special characters | Use `escapeMarkdownV2()` on ALL dynamic text |
| `initData` empty in dev | Running outside Telegram | Use the signed `mockDevEnvironment()` (real HMAC), not a fake `hash` string |
| API 401 in local dev | Mock `hash` doesn't match backend token | Sign mock initData with `DEV_BOT_TOKEN` and validate against it in dev (see §2) |
| `x is not available` / throws on call | Capability missing on this client/version | Guard every bridge call with `x.isAvailable()` / `x.ifAvailable()` |
| Rate limit never trips on Vercel | In-memory counter resets per invocation | Use Upstash/Vercel KV shared store (see §13) |
| Fullscreen content hidden by status bar | Safe-area insets ignored | Pad with `--tg-safe-area-inset-top` etc. |
### Debug Webhook Locally
```bash
# Use ngrok to expose local server
ngrok http 3000
# Set webhook to ngrok URL
WEBHOOK_URL=https://abc123.ngrok.io/api/bot npx tsx scripts/set-webhook.ts
# Watch logs
npm run dev
```
### Verify Webhook Status
```bash
curl "https://api.telegram.org/bot${BOT_TOKEN}/getWebhookInfo" | jq
```
Response should show:
- `url` → your webhook URL
- `has_custom_certificate` → false (Vercel handles TLS)
- `pending_update_count` → 0 (no backlog)
- `last_error_message` → check this if updates aren't arriving
### Test Stars Payment in Dev
Stars payments work in Telegram's test environment:
1. Create a test bot via the **test-server** @BotFather (not the production one). You must log into the test server Telegram app first — the token from the production @BotFather will NOT work on test servers and vice versa.
2. Use Telegram test apps (available on Android/iOS test builds)
3. Test bots use the `https://api.telegram.org/bot/test/METHOD` format (append `/test/` before the method name)
Or test on production with 1-Star items and refund immediately after.
---
## Quick Reference
### Environment Variables Needed
```
BOT_TOKEN # From @BotFather (production/test bot)
DEV_BOT_TOKEN # Throwaway bot token for signing mock initData (dev only)
NEXT_PUBLIC_DEV_BOT_TOKEN # Same value, exposed client-side (dev only)
MINI_APP_URL # Your deployed frontend URL
WEBHOOK_URL # Your /api/bot endpoint
WEBHOOK_SECRET # Random 32+ char string for webhook auth
DATABASE_URL # file:local.db for dev
TURSO_DATABASE_URL # libsql://... for production
TURSO_AUTH_TOKEN # Turso auth token for production
UPSTASH_REDIS_REST_URL # Serverless-safe rate limiting
UPSTASH_REDIS_REST_TOKEN # Serverless-safe rate limiting
```
### Key API Methods
| Method | Use |
|--------|-----|
| `bot.api.createInvoiceLink(...)` | Create a Stars invoice link for in-app `openInvoice` (no chat needed) |
| `openInvoice(link, "url")` (client) | Open the native Stars payment sheet in-app |
| `bot.api.sendInvoice(chatId, ...)` | Push an invoice message to a chat (requires open chat with bot) |
| `ctx.answerPreCheckoutQuery(true)` | Approve checkout (within 10s) |
| `ctx.answerPreCheckoutQuery(false, "error message")` | Reject checkout |
| `bot.api.refundStarPayment(userId, chargeId)` | Refund a Stars payment |
| `bot.api.getStarTransactions()` | Reconcile/audit Stars balance |
| `bot.api.setWebhook(...)` / `getWebhookInfo()` | Set / check webhook |
| `cloudStorage.{setItem,getItem,getKeys,deleteItem}` (client) | Per-user KV cache (guard with `isAvailable()`) |
| `biometry.{requestAccess,authenticate,updateToken}` (client) | Device-gated local token (not server auth) |
| `viewport.{requestFullscreen,exitFullscreen}` (client) | Fullscreen (WebApp 8.0+) |
| `shareStory(mediaUrl, opts)` / `shareMessage(id)` (client) | Virality / sharing |
### initData Validation Flow
```
Client sends: Authorization: tma
│
▼
Parse URLSearchParams
│
▼
Extract & remove `hash`
│
▼
Sort remaining params by key
│
▼
Join as "key=value\nkey=value"
│
▼
secretKey = HMAC-SHA256("WebAppData", BOT_TOKEN)
│
▼
computed = HMAC-SHA256(secretKey, dataCheckString)
│
▼
Timing-safe compare with hash
│
▼
Check auth_date < 24h old
│
▼
✅ Trust user data
```
---
## Rules for the Agent
1. **Always validate initData server-side** — never trust the client
2. **Guard every SDK bridge call** — `x.isAvailable()` / `x.ifAvailable()`; capabilities vary by client/version (SDK v3)
3. **Pin `@telegram-apps/sdk` v3** — there is no npm "SDK 7.x"; that number is the Telegram WebApp *platform* version
4. **Prefer `openInvoice` for in-app purchases** — `sendInvoice(chatId, …)` needs an open chat and 403s otherwise
5. **Always escape dynamic text in MarkdownV2** — use `escapeMarkdownV2()`
6. **Answer `pre_checkout_query` FAST** — do validation only, defer DB writes to `successful_payment`
7. **Use `"XTR"` for Stars currency** — not "STARS" or "stars"; pass empty string `""` for `provider_token`
8. **Use Telegram theme CSS variables** — call `themeParams.bindCssVars()`, never hardcode colors
9. **Set webhook secret** — validate `X-Telegram-Bot-Api-Secret-Token` header
10. **Rate limit with a shared store** — Upstash/Vercel KV, never in-memory on serverless
11. **CloudStorage and biometry are client-side** — keep entitlements/auth on the server, keyed by validated `user.id`
12. **Use Turso for production** — SQLite for dev, Turso for distributed edge
13. **Log all payment events & reconcile** — audit trail via DB + `getStarTransactions`
14. **Return 200 to Telegram webhooks even on error** — prevents retry storms
15. **Sign mock initData in dev** — never a fake `hash`; validate against `DEV_BOT_TOKEN` locally