---
name: use-telegram-serverless
description: Build, architect, review, test, deploy, and debug Telegram bots and Mini Apps on Telegram Serverless using tgcloud, its V8 JavaScript SDK (sdk, sdk/db, sdk/api, sdk/fetch), SQLite-backed database, and static hosting. Use when working on Telegram Serverless projects, tgcloud/, tgcloud.jsonc, update handlers, authenticated Mini App endpoints (Telegram.WebApp.Serverless.call), schema migrations, Telegram Stars payments, stateful bots, or tgcloud CLI operations; not for generic bots hosted on external servers (VPS, Cloudflare, Vercel, AWS).
license: MIT
compatibility: Portable across Agent Skills hosts (Claude Code, Cursor, Codex, Antigravity, Gemini, GitHub Copilot, Windsurf, OpenCode, Cline). Local checks require no network. Remote testing, deployment, and migrations require Node.js >=18, the project-local @tgcloud/cli, and an authorized Telegram Serverless CLI access token.
metadata:
  author: rijans
  category: engineering-workflows
  version: "1.0.0"
---

# Use Telegram Serverless

Architect, build, review, test, deploy, and troubleshoot bots and full-stack Mini Apps on [Telegram Serverless](https://core.telegram.org/bots/serverless), maintaining strict separation between offline local verification, remote sandbox execution (`tgcloud run`), live deployment (`tgcloud push`), and database schema migration (`tgcloud migrate`).

## When to Use

- The user mentions **Telegram Serverless**, `tgcloud`, `@tgcloud/cli`, `@tgcloud/bot`, or works in a repository containing `tgcloud/` or `tgcloud.jsonc` / `tgcloud.json`.
- The task involves building or modifying Telegram Serverless **update handlers** (`tgcloud/handlers/*.js`), **Mini App endpoints** (`tgcloud/endpoints/*.js`), **shared modules** (`tgcloud/lib/**/*.js`), **SQLite schemas** (`tgcloud/schema.js`), or **Mini App static hosting** (`https://app<app_id>.tgcloud.ai/`).
- The user wants to implement advanced bot or Mini App capabilities on Telegram Serverless: conversational state machines, callback routers, Telegram Stars/payments, inline queries, AI/LLM streaming replies via `sdk/fetch`, or `Telegram.WebApp.Serverless.call` RPC wrappers.
- An existing Telegram Serverless project needs code review, security auditing, schema migration planning, local/cloud conflict recovery, webhook synchronization, or legacy layout upgrading.

## When Not to Use

- A Telegram bot is intentionally hosted on a VPS, Docker container, Cloudflare Workers, AWS Lambda, Vercel, or another non-Telegram runtime (using frameworks like `grammY`, `Telegraf`, or `aiogram`). Do not migrate external bots to Telegram Serverless unless explicitly asked.
- The task only involves generic frontend styling unrelated to Telegram Mini App SDK integration or `tgcloud.jsonc` static hosting.
- A requested feature requires a capability not supported by the Telegram Serverless V8 isolate runtime (such as raw TCP sockets, background cron daemons, native Node.js C++ addons, or filesystem persistence outside SQLite). Explain the platform constraint first before proposing workarounds or external architectures.

## Inputs to Inspect First

Before modifying files or running commands, inspect what exists locally:

1. **Project instructions & docs**: `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, and the scaffolded `docs/tgcloud-sdk.md` (treat `docs/tgcloud-sdk.md` and installed `@tgcloud/cli` files as version-specific evidence, while user instructions govern task scope).
2. **Configuration & toolchain**: `package.json` (scripts, package manager, `@tgcloud/cli` version), lockfiles, `tgcloud.jsonc` or `tgcloud.json`, and Node.js version.
3. **Codebase & Git state**: `tgcloud/schema.js`, `tgcloud/handlers/`, `tgcloud/endpoints/`, `tgcloud/lib/`, frontend source/build directories, and `git status` / `git diff`.
4. **Never inspect secrets or hand-edit CLI state**: Do not read, print, or modify credential files inside `.tgcloud/` or environment variables containing `TGCLOUD_TOKEN`.

Use [sources.md](references/sources.md) when you need to verify authoritative platform contracts or check version-sensitive limits.

## Workflow & Routing

Select the route that matches the user's authorized intent and load **only** the minimum required references:

| Route | Outcome | Primary Reference (Read First) | Conditional Reference (Read Only If Needed) |
| :--- | :--- | :--- | :--- |
| **1. Explain, Audit, or Review** | Explain behavior or report concrete code/security/migration findings without modifying state | Relevant domain reference | [Debugging & Audit Playbook](references/debugging-playbook.md) (for audits) |
| **2. Set Up, Scaffold, or Link** | Create a project (`npm create @tgcloud/bot` / `tgcloud init`), add modules (`tgcloud add`), or guide `tgcloud login` | [Setup & Auth](references/setup.md) | — |
| **3. Build or Modify a Bot** | Implement update handlers (`tgcloud/handlers/`), shared `lib/` modules, Bot API calls, or HTTP integrations | [Runtime & SDK](references/runtime-sdk.md) | [Database](references/database.md) (if stateful), [Patterns & Recipes](references/patterns-and-recipes.md) (only for wizards, payments, callbacks, LLM, or inline) |
| **4. Build or Modify a Mini App** | Implement authenticated `tgcloud/endpoints/`, frontend `Serverless.call`, and `tgcloud.jsonc` static hosting | [Mini Apps](references/mini-apps.md) | [Patterns & Recipes](references/patterns-and-recipes.md) (for Promise RPC wrapper / RBAC), [Database](references/database.md) (if querying DB) |
| **5. Design or Evolve Database** | Author `tgcloud/schema.js`, write atomic `sdk/db` queries, or plan/execute safe schema migrations | [Database & Migrations](references/database.md) | — |
| **6. Validate & Test** | Run offline checks (syntax, layout, ownership, mocks) or authorized remote execution (`tgcloud run`) | [Operations](references/operations.md) | [Debugging & Audit Playbook](references/debugging-playbook.md) (if tests fail) |
| **7. Deploy Changes** | Build static assets (if applicable) and publish reviewed modules/assets via targeted or full `tgcloud push` | [Operations](references/operations.md) | [Mini Apps](references/mini-apps.md) (if static hosting is configured) |
| **8. Diagnose, Sync, or Upgrade** | Troubleshoot failures, resolve local/cloud divergence, sync webhooks, or run `tgcloud upgrade` | [Debugging & Audit Playbook](references/debugging-playbook.md), [Operations](references/operations.md) | [Setup](references/setup.md) (for auth or legacy layout issues) |
| **9. Full-Stack End-to-End Build** | Sequence Database Schema $\rightarrow$ Shared `lib/` $\rightarrow$ Bot Handlers $\rightarrow$ Mini App Endpoints & Frontend $\rightarrow$ Validation | [Database](references/database.md), [Runtime & SDK](references/runtime-sdk.md), [Mini Apps](references/mini-apps.md) | [Patterns & Recipes](references/patterns-and-recipes.md) (only for advanced recipes used) |

### Routing & Design Alignment ("Grill When Ambiguous, Execute When Clear")

- **Clear, well-specified intent**: Announce the selected route and execute directly without unnecessary questions.
- **Architectural or product forks (Interview the Developer First)**:
  - Always resolve facts discoverable from the repository (`package.json`, `tgcloud/`, `tgcloud.jsonc`, `git status`) **before** asking the user anything.
  - When genuine design trade-offs exist that cannot be answered from the codebase—such as:
    1. *Bot-only inline keyboard flow vs. full Mini App (`endpoints/` + static frontend)*,
    2. *Stateless handler vs. persistent SQLite schema design*,
    3. *Safe additive schema evolution vs. destructive `.deprecated()` drop or manual type migration*, or
    4. *How to handle external third-party API secrets given no runtime `process.env`*—
    **ask concise, high-leverage clarifying questions (one at a time, leading with a recommended default)** to align on the design before writing multi-file implementations.
- **Bare skill invocation, conflicting scope, or options inquiry**: Present the route table above and wait for the user's choice before running state-changing commands.
- **Review or diagnosis requests**: Report findings and exact remediation steps; do not modify files or run mutating CLI commands unless explicitly asked to apply the fix.

### Context Efficiency & Live Documentation Hierarchy

Never read all reference files upfront. Follow this 3-tier lookup hierarchy to minimize context usage while staying 100% accurate:

1. **Tier 1 — Selective Skill Reference (1–2 files max)**: Read only the **Primary Reference** for your active route from the table above. Load a **Conditional Reference** only if the task specifically requires it.
2. **Tier 2 — Project-Local Version Evidence (Offline)**: When working in an initialized repo, inspect `docs/tgcloud-sdk.md` and `node_modules/@tgcloud/cli/schema/tgcloud.json` (if present) to verify the exact SDK and config schema matching the project's installed `@tgcloud/cli` version.
3. **Tier 3 — Targeted Live Documentation Fetch (When Needed)**: Consult [sources.md](references/sources.md) and fetch the live URL (`https://core.telegram.org/bots/serverless#<anchor>`, `https://core.telegram.org/bots/api`, or `https://registry.npmjs.org/@tgcloud%2Fcli/latest`) **only** when:
   - The user asks about newly released Telegram Serverless features or CLI upgrades,
   - The installed `@tgcloud/cli` version is newer than `0.2.0` or behaves differently than documented, or
   - You need to verify exact parameters for an uncommon Bot API method or Mini App `WebApp` event.

### Anti-Overengineering & Right-Sizing Rules

Build the **smallest, cleanest solution** that satisfies the user's request:

- **No speculative abstractions**: Do not create `tgcloud/lib/` routers, session state machines, idempotency tables, or RPC wrappers for a simple bot that only needs a 15-line `tgcloud/handlers/message.js`.
- **No unused handlers**: Telegram Serverless spins up an isolate for every non-empty file in `tgcloud/handlers/`. Never scaffold handler files for update types the bot does not actively handle.
- **No unnecessary tables or columns**: Only add `tgcloud/schema.js` exports when persistent state is actually required by the feature.
- **Smallest safe diff**: When editing an existing project, preserve its coding style, frontend framework, and module structure; change only the files required for the task.

### Execution Sequence

1. **Establish Context & Scope**: Identify the target directory, bot/app identity (without exposing secrets), existing uncommitted changes, and which actions are authorized (offline-only vs. remote `run` vs. `push` vs. `migrate`).
2. **Load Targeted References & Align on Choices**: Load only the active route's reference(s). If architectural trade-offs remain, clarify with a recommended option before coding.
3. **Implement Minimal, Safe Changes**:
   - Keep backend imports strictly within `tgcloud/` using relative `.js` paths (`../schema.js`, `../lib/util.js`) and built-in SDK specifiers (`sdk`, `sdk/db`, `sdk/api`, `sdk/fetch`).
   - When evolving an existing live database alongside code, sequence **schema-only push $\rightarrow$ authorized `migrate` $\rightarrow$ consumer handler/endpoint push** so deployed code never queries missing tables or columns.
4. **Verify Offline First, Then Remote**:
   - Run local checks (`git diff`, `tgcloud diff`, Node syntax check `node --check`, static build verification) before any cloud command.
   - Obtain explicit user confirmation before running any command with remote side effects (`tgcloud run`, `tgcloud push`, `tgcloud migrate`, `tgcloud webhook sync`, `tgcloud pull`) unless already authorized for that specific target and operation.
5. **Report Evidence Accurately**: Distinguish between local syntax/mock checks, remote sandbox execution (`tgcloud run`), deployed module state (`tgcloud push`), and applied database migrations (`tgcloud migrate`). Never claim a change is live or migrated based solely on local file edits or a zero exit code when manual steps were skipped.

## Safety & Security Guardrails

- **`tgcloud run` is remote execution, not a local unit test**: `npx tgcloud run` uploads your local `tgcloud/` modules to Telegram's cloud and executes them against the **live database, live Bot API, and live external HTTP endpoints** (without publishing the code). Furthermore, `--ctx` is synthetic and **does not verify** real Mini App `initData` signatures.
- **Separate authorities for `push`, `migrate`, `run`, and `webhook sync`**: Authorization for one never implies authorization for another. Remember that a full `tgcloud push` (with no path arguments) mirrors local `tgcloud/` and **deletes** remote modules that do not exist locally. Prefer targeted `npx tgcloud push <module...>` when working on a subset of an existing bot.
- **Protect local work and never force-overwrite**: Before running `tgcloud pull`, `tgcloud reset`, or `tgcloud upgrade`, check for uncommitted local edits. Never resolve a revision conflict by automatically running `push --force`, `reset`, or `webhook sync --drop-pending`.
- **Credential & token isolation**:
  - The Serverless CLI access token (`app<id>:<secret>`, obtained from `@BotFather` $\rightarrow$ Bot $\rightarrow$ Serverless $\rightarrow$ CLI Access) is distinct from the Bot API token.
  - Never ask the user to paste tokens into chat, never pass tokens as command-line arguments, never log them, and never embed them in `tgcloud/` modules or Mini App frontend files. Use interactive `npx tgcloud login` in the user's terminal or pre-configured `TGCLOUD_TOKEN` in CI.
- **Zero-trust Mini App authorization**:
  - In `tgcloud/endpoints/<name>.js`, always derive caller identity from platform-verified `ctx.initData.user.id`.
  - Never trust a `userId` passed inside `input` or client-side `WebApp.initDataUnsafe`.
  - Identity is not authorization: always scope database `SELECT`/`UPDATE`/`DELETE` queries with ownership predicates (e.g., `and(eq(items.id, input.id), eq(items.userId, ctx.initData.user.id))`).
- **No hallucinated runtime capabilities**:
  - Telegram Serverless runs in a V8 isolate, **not** Node.js. There is no `fs`, `path`, `Buffer`, `process.env`, `crypto` (use Web Crypto `globalThis.crypto`), or `node_modules` at runtime.
  - Do not invent `sdk.secrets`, database foreign keys (`.references()` fails), multi-statement transaction guarantees, built-in cron schedulers, or CLI backup commands.

## Skill Composition ("Superpowers")

When appropriate, combine `use-telegram-serverless` with companion skills and workflows:

- **Bot Copy & UX Microcopy (`humanize-text`)**: Apply natural, concise, non-robotic prose to bot replies, `/start` onboarding messages, inline results, and `EndpointError` user-facing descriptions.
- **Mini App Frontend Design**: Pair authenticated `tgcloud/endpoints/` and `Telegram.WebApp.Serverless.call` with Telegram theme variables (`var(--tg-theme-bg-color)`, `MainButton`, `BackButton`, `HapticFeedback`) for native-feeling Mini Apps.
- **Architectural Recipes**: Use [patterns-and-recipes.md](references/patterns-and-recipes.md) for drop-in patterns covering SQLite state machines, 64-byte callback routers, Telegram Stars payments, LLM streaming via `sdk/fetch`, and Promise-based Mini App RPC clients.

## References (Progressive Disclosure)

Load only the references needed for your current route:

- [Setup & Authentication](references/setup.md): Prerequisites, `npm create @tgcloud/bot`, `tgcloud init`/`add`/`login`, `TGCLOUD_TOKEN`, BotFather sync, shell completion, legacy `upgrade`.
- [Runtime & SDK](references/runtime-sdk.md): V8 isolate contract, ES module imports, all `handlers/<update_type>.js` signatures, `api.<method>`, `BotApiError`, `InputFile` (`Uint8Array`), `getFileContent`/`getFileStream`, `fetch` & `FormData`, logging.
- [Database & Migrations](references/database.md): Complete `sdk/db` schema DSL (`table`, column types, encoding modes, indexes/constraints), no-foreign-keys contract, async query builder & operators cheat sheet, raw SQL, batch chunking, `migrate` flags (`--dry-run`, `--local`, `--safe`, `--yes`), `.deprecated()` drops, and manual type migrations.
- [Mini Apps & Static Hosting](references/mini-apps.md): `endpoints/<name>.js` contract, `ctx.initData` security, `EndpointError`, `Telegram.WebApp.Serverless.call`, and full `tgcloud.jsonc` static hosting configuration (`source`, `spa`, `immutable`, `headers`, `redirects`).
- [Operations & CLI Lifecycle](references/operations.md): CLI command side-effect matrix (`status` network caveat, `diff`, `fetch`, `run`, `push`, `migrate`, `pull`, `reset`, `webhook`, `upgrade`), offline vs. remote testing, conflict recovery, and CI/CD pipelines.
- [Patterns, Recipes & Superpowers](references/patterns-and-recipes.md): Production blueprints for SQLite state machines/wizards, callback query routers, deep linking, Telegram Stars payments, AI/LLM streaming bots, Promise-based Mini App RPC wrappers, inline mode, RBAC, and idempotency.
- [Debugging & Audit Playbook](references/debugging-playbook.md): Symptom $\rightarrow$ Root Cause $\rightarrow$ Safe Fix matrix and pre-deployment security/code audit checklist.
- [Sources & Platform Coverage](references/sources.md): Authoritative section map of `core.telegram.org/bots/serverless`, npm package specs, and platform limits/unresolved capabilities.

## Evaluation & Self-Check

Before returning substantial code, reviews, or operational reports, verify your work against [eval.md](eval.md).

## Output Format

Structure your response to match the task:

- **Selected Route & Scope**: State the active workflow route and the files/modules inspected or changed.
- **Verification & Operational Status** (include for code, test, deploy, or migration tasks; omit ceremonies for brief explanations):
  - **Local checks**: Syntax, layout, schema/query verification, or static build results.
  - **Remote execution (`tgcloud run`)**: Command, synthetic payload/context used, console output/return value, or `Not run`.
  - **Deployment (`tgcloud push`) & Webhook state**: Revision/modules published, static URL (`https://app<app_id>.tgcloud.ai/`), webhook sync status, or `Not run`.
  - **Database migration (`tgcloud migrate`)**: Applied, skipped, warning, manual, or undocumented changes, or `Not run`.
- **Bot / Project Identity**: Non-sensitive identifier (e.g., `app<id>` or project folder) and confirmation that existing local work and credentials were preserved.
- **Next Steps & Caveats**: Any remaining manual steps, required user authorizations, or platform limitations.

## Completion Criteria

1. The requested bot, Mini App, schema, review, or operational task is complete within the user's authorized scope.
2. All generated backend code complies strictly with the Telegram Serverless V8 isolate contract (relative `.js` imports, no Node.js builtins, no foreign keys, awaited `db` terminals, verified `ctx.initData.user.id` ownership).
3. Local checks are distinguished from cloud execution; no deployment or migration is claimed unless actually executed and verified.
4. A database migration is only reported as complete when `tgcloud migrate` finishes with zero remaining required skipped or manual steps.

## Failure Modes & Recovery

- **Missing CLI, Node.js, or authentication**: Report the exact missing prerequisite, complete all possible offline file edits and local checks, and provide the exact command for the user to run once authenticated. Do not run `npx` commands that silently download packages during a read-only audit.
- **Local vs. Cloud revision conflict**: Stop immediately. Do not run `push --force` or `reset`. Preserve the local working tree, run `tgcloud fetch` + `tgcloud diff` (when authorized), and present the divergence for user decision.
- **Unsupported platform capability**: Cite [sources.md](references/sources.md), pause the dependent step, and offer a documented Telegram Serverless workaround (from [patterns-and-recipes.md](references/patterns-and-recipes.md)) before suggesting external hosting.