mititgcloudbot

A sample Telegram bot and Mini App running on Telegram Serverless (tgcloud). There is no server: Telegram runs the code in tgcloud/ next to the Bot API, with a built-in SQLite database, and hosts the Mini App build at https://app<app_id>.tgcloud.ai/.

What it does

• Any message: the bot stores the sender in the users table, increments their message count, and replies with the running total.
• /start: greets the user and, once MINI_APP_URL is set, shows an "Open stats" button.
• /zen: fetches a line from https://api.github.com/zen through the SDK's fetch.
• Mini App: calls the getStats endpoint and shows the user's count, join date, and bot-wide totals.

Layout

Path	Purpose
tgcloud/schema.js	users table
tgcloud/handlers/message.js	Message handler (/start, /zen, counter)
tgcloud/endpoints/getStats.js	POST /api/getStats, called by the Mini App
tgcloud/lib/	Shared code: user queries, GitHub Zen fetch, MINI_APP_URL
index.html, src/	Vite Mini App front-end (plain JavaScript)
tgcloud.jsonc	Hosts the dist build folder as the Mini App

AGENTS.md and docs/tgcloud-sdk.md are the platform's own guides, generated by npm create @tgcloud/bot.

Setup

Requires Node.js 18 or newer.

1. Create a bot with @BotFather and enable Serverless for it in BotFather's bot settings.

2. Install dependencies and link the project to the bot. login asks for the CLI token (app<id>:<secret>) from the BotFather Serverless menu and stores it in the gitignored .tgcloud/ folder.

   npm install
   npx tgcloud login

3. Build the Mini App and deploy the code, then create the users table:

   npm run deploy
   npx tgcloud migrate

4. Copy the Mini App URL that push printed into tgcloud/lib/config.js and run npm run deploy again. Optionally, set it as the bot's menu button or Main Mini App in BotFather.

Development

npm run lint     # ESLint with JSDoc rules
npm run build    # build the Mini App into dist/
npx tgcloud status
npx tgcloud run handlers/message '{ chat: { id: <your chat id> }, from: { id: <your user id>, first_name: "Test" }, text: "hi" }'
npx tgcloud run endpoints/getStats '{}' --ctx '{ initData: { user: { id: <your user id> } } }'

tgcloud run executes on the platform against local files without deploying, so it touches the real database and sends real messages.

Runtime limits: modules may import only sdk and other project modules (no npm packages, no filesystem), and the database has no foreign keys.