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/runtime-sdk.md
View on GitHub# Runtime and SDK
Read for bot code, shared modules, integrations, or code review. Sources: [projects](https://core.telegram.org/bots/serverless#projects-and-modules), [SDK](https://core.telegram.org/bots/serverless#the-sdk), [Bot API](https://core.telegram.org/bots/api).
## Code boundary and entrypoints
The backend is JavaScript ES modules in a V8 sandbox, not a Node.js server. There is no backend npm resolution, filesystem, Node Buffer, or server entrypoint. Use relative imports ending in `.js` within `tgcloud/`; SDK imports are `sdk`, `sdk/db`, `sdk/api`, and `sdk/fetch`. Do not import frontend dependencies or files outside that tree. Frontend packages are a separate build concern.
`schema.js` exports tables. Flat `handlers/` files have a default function for the matching Bot API update type. Empty/missing handlers ignore that update type. Flat `endpoints/` files are called by a Mini App. Shared `lib/` files can have subdirectories.
A message handler receives a Message directly, not an Update envelope. Its second argument contains `ctx.update`, including the raw update ID when needed. A callback-query handler instead receives a CallbackQuery. Validate optional fields for the actual update type.
Original example, accepting only text messages:
```js
import { api } from "sdk";
export default async function (message) {
if (typeof message.text !== "string") return;
await api.sendMessage({
chat_id: message.chat.id,
text: message.text === "/start" ? "Send a note to get started." : "Text received.",
});
}
```
Do not assume invocation-global memory persists. Use the database for persistent state. Do not claim undocumented ordering, retry, isolation, or exactly-once delivery guarantees; make duplicate-sensitive effects explicit in the application design.
## Database access
Import `db` from `sdk` and schema/operators from `sdk/db` plus the local schema. Await terminal operations. Read [database](database.md) before designing schema, atomic updates, or migrations. Drizzle resemblance does not make all Drizzle APIs supported.
## Bot API and errors
`api.<method>(params)` uses Bot API method names and snake_case parameters. Successful calls return the unwrapped result. A failed API call throws `BotApiError` with code, description, method, and parameters, including retry information when provided.
Catch only the failure you can identify and recover from. A generic 400 does not prove that a message was already deleted. Do not swallow all failures or retry non-idempotent actions blindly. Use current Bot API documentation for method parameters and limits rather than copying an exhaustive method list into the skill.
## Files
`InputFile` wraps byte data, a filename, and optional MIME type for Bot API uploads; nested media fields are supported. Use `Uint8Array`, not Node Buffer.
`api.getFileContent(file_id)` returns all bytes. `api.getFileStream(file_id)` returns file information and a body stream. These helpers resolve downloads without exposing a bot token or constructing token-bearing URLs. Verify current upload/download limits before committing to a payload size; streaming is not a bypass.
## HTTP
Import `fetch` from `sdk`. It supports HTTP requests, response status/headers, text/JSON readers, and incremental response bodies. Check `res.ok` before interpreting success. Its response-size cap still applies when streaming.
`fetch.body.json`, `form`, and `text` helpers choose matching content types. Request bodies can include bytes, InputFile, or the SDK's FormData. Do not assume every browser/Node fetch option, global, or binary response helper exists; use the generated/current SDK guide.
For external authenticated APIs, first establish a documented runtime secret mechanism. `TGCLOUD_TOKEN` belongs to the CLI, and client-side Mini App SecureStorage is not a server secret store. Do not invent `process.env`, `sdk.secrets`, or hardcode provider credentials when the requested integration needs an unresolved capability.
## Logging and verification
The runtime console is available globally. Remote run reports logs, origins, return value, and elapsed time. Log useful event/error categories without credentials, whole message bodies, or unnecessary user data.
Use syntax checks and offline tests for pure logic when possible. They do not resolve the production SDK or prove Telegram delivery. Remote run can produce real effects and requires the target and authority described in [operations](operations.md).
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 |