stark-ai-de/agent-skills / plugins/stark-ai-developer/skills/telegram-serverless
telegram-serverless
VerifiedBuild, review, deploy, and troubleshoot bots and Mini Apps on Telegram Serverless using tgcloud, its JavaScript SDK, and built-in database. Use when working on Telegram-hosted projects, handlers, endpoints, schema changes, or tgcloud operations; not generic Telegram bots hosted elsewhere or unrelated serverless platforms.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.7 KB |
| agents/openai.yaml | config | 530 B |
| assets/openai-icon.png | binary | 7.7 KB |
| assets/openai-icon.svg | other | 708 B |
| references/database.md | markdown | 6.2 KB |
| references/mini-apps.md | markdown | 6.4 KB |
| references/operations.md | markdown | 7.4 KB |
| references/runtime-sdk.md | markdown | 4.4 KB |
| references/setup.md | markdown | 3.8 KB |
| references/sources.md | markdown | 13.1 KB |
references/mini-apps.md
View on GitHub# Mini Apps
Read for route 4 and Mini App deployment diagnosis. Sources: [endpoints](https://core.telegram.org/bots/serverless#endpoints), [frontend hosting](https://core.telegram.org/bots/serverless#mini-app-front-end), [Serverless.call](https://core.telegram.org/bots/webapps#serverless).
## Endpoint boundary
A flat module `tgcloud/endpoints/getNote.js` exposes getNote through the platform. Names use letters, digits, and underscores and cannot start with a digit. The default export receives `(input, ctx)`; input is the JSON object supplied by the frontend, and `ctx.initData` is verified by the platform during ordinary Mini App calls.
Use `ctx.initData.user.id` as the authenticated caller. This establishes identity, not authorization to arbitrary records. Validate input and constrain reads/writes to that caller or explicit application roles. Never trust a submitted userId or client-side initDataUnsafe as backend authorization.
Original endpoint using the owned lookup from the database reference:
```js
import { EndpointError } from "sdk";
import { ownedNote } from "../lib/notes.js";
export default async function (input, ctx) {
if (!Number.isSafeInteger(input?.noteId) || input.noteId <= 0) {
throw new EndpointError("Choose a valid note.", { code: "INVALID_NOTE" });
}
const note = await ownedNote(ctx.initData.user.id, input.noteId);
if (!note) throw new EndpointError("Note not found.", { code: "NOT_FOUND" });
return { id: note.id, body: note.body };
}
```
Ordinary calls without valid init data are rejected by the platform before the endpoint runs. CLI run with supplied `--ctx` does not verify this context and cannot prove that authentication behavior.
Return JSON-serializable values. EndpointError intentionally exposes its description and optional parameters to the caller; keep those public-safe. Other exceptions become a generic client error with details retained in logs. Put stable business error codes in parameters when needed.
Endpoints are for the bot's Mini App, not generic unauthenticated webhook ingress. Do not promise a public integration endpoint by bypassing init data checks.
## Frontend call and UI
Include the official Mini Apps script, `https://telegram.org/js/telegram-web-app.js`. Call `Telegram.WebApp.Serverless.call(name, input?, callback)`; the SDK transmits init data. The callback receives an error or result, not a returned Promise.
Minimal original HTML behavior:
```html
<button id="load-note" type="button" disabled>Load note</button>
<p id="result" role="status"></p>
<script src="https://telegram.org/js/telegram-web-app.js"></script>
<script>
const button = document.getElementById("load-note");
const result = document.getElementById("result");
const webApp = window.Telegram?.WebApp;
const serverless = webApp?.Serverless;
const available =
typeof serverless?.call === "function" &&
typeof webApp?.initData === "string" &&
webApp.initData.length > 0;
if (!available) {
result.textContent =
"This launch does not provide Mini App init data or Serverless support. Open the app through a Telegram Mini App launch that provides both.";
} else {
button.disabled = false;
button.addEventListener("click", () => {
button.disabled = true;
result.textContent = "Loading…";
const finish = (error, note) => {
button.disabled = false;
result.textContent = error
? error.type === "ENDPOINT_ERROR"
? error.message
: error.type === "UNAUTHORIZED"
? "Reopen this app in Telegram."
: "Unable to load the note."
: note.body;
};
try {
serverless.call("getNote", { noteId: 1 }, finish);
} catch {
finish({ type: "CLIENT_ERROR" });
}
});
}
</script>
```
The fixed note ID is an example resource ID, not a caller identity. Real apps select their resource through UI state. Preserve a user's existing framework; the example establishes only the platform contract.
The SDK exposes Serverless even outside Telegram; its presence alone is insufficient. Missing init data causes a synchronous exception before any callback. Check both prerequisites and catch synchronous SDK failures so pending controls recover. These frontend checks gate the UI only; server-verified context still owns authentication.
Handle unavailable SDK, pending, success, business errors, unauthorized/transport failures, and retries appropriate to the action. Use textContent or framework escaping for returned text. Client error fields include message, optional type/parameters, and HTTP status (0 for an incomplete request).
## Static hosting
The project root holds frontend source; only its built output is hosted. Configure `static.source` in the existing tgcloud.jsonc (JSON with comments) or strict tgcloud.json. Use the installed CLI's JSON schema for detailed validation.
Example config for an existing dist build:
```json
{
"$schema": "./node_modules/@tgcloud/cli/schema/tgcloud.json",
"static": {
"source": "dist",
"spa": true,
"immutable": ["/assets/*"]
}
}
```
- Vite-style builds commonly use dist. SSR-oriented frameworks need a verified static export and explicit source folder; do not deploy their server output.
- The CLI does not build on push. Run and verify the actual build script before publishing, or inspect a deploy script that builds before pushing.
- spa supplies index.html for eligible extensionless paths, not missing files with extensions.
- immutable is only for content-hashed files; marking mutable HTML/config can leave clients stale for a year.
- Headers use exact paths or prefix patterns; null removes a header. Redirects are first-match, with existing files taking priority.
- `"static": "dist"` is a shorthand. `static: false` removes the hosted site on the next push; removing the key stops management and leaves existing hosted files.
- Dotfiles are excluded. Keep secrets out of the entire build, including public configuration and source maps.
- The host serves from /. Reserve /api/ for platform endpoints. Keep Telegram Web iframe embedding compatible: do not add X-Frame-Options or a restrictive frame-ancestors policy.
A full push combines modules and static output; targeted module pushes leave static content alone. Static-only publishing can target the configured build folder. Use the exact URL reported by the successful push for the owner's BotFather Mini App configuration. Local builds and mocked calls do not establish live hosting or Telegram-client access.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |