# [Bot Name] · Telegram bot

A Telegram bot. Webhook-driven so it scales without polling. Inline keyboards, conversation state in Redis, payments via Telegram Stars.

## Source of truth
GitHub. Deployed as a webhook receiver on Cloudflare Workers (small bots) or Fly.io (larger). Telegram's BotFather is the source of truth for token + commands list.

## Tech stack
Node 22 + TypeScript + grammY 1.x (the modern Telegram framework). Redis for conversation state (sessions, multi-turn flows). Postgres for persistent data. Optional: `@grammyjs/conversations` for state-machine flows, `@grammyjs/menu` for inline keyboards.

## Deploy
- Set webhook: `curl 'https://api.telegram.org/bot<TOKEN>/setWebhook?url=https://yourdomain.com/webhook'`
- Verify: `curl 'https://api.telegram.org/bot<TOKEN>/getWebhookInfo'`
- Code: `fly deploy` or `wrangler deploy`

## File map
- `src/bot.ts` grammY instance + plugin registration
- `src/webhook.ts` HTTP entrypoint (Express, Hono, or Cloudflare Worker fetch)
- `src/handlers/commands/` one file per command (`/start.ts`, `/help.ts`)
- `src/handlers/callbacks/` callback query handlers (inline keyboard taps)
- `src/conversations/` multi-turn flows (signup, booking)
- `src/menus/` reusable inline menus
- `src/lib/db.ts`, `src/lib/redis.ts`

## .env keys
- `TELEGRAM_BOT_TOKEN` from BotFather
- `TELEGRAM_WEBHOOK_SECRET` for signature verification
- `DATABASE_URL`
- `REDIS_URL`

## Hard rules
- Webhook secret in the URL path (e.g. `/webhook/<secret>`) OR validated via `X-Telegram-Bot-Api-Secret-Token`. Anyone can hit your URL otherwise.
- Telegram expects a 200 response within 60 seconds. Long work goes to a queue; reply with a placeholder message immediately.
- File downloads via `bot.api.getFile` -> URL. Large files (>20MB) need bot API "local mode" or a different transport.
- Inline keyboard callback data is a 64-byte limit. Don't shove JSON in there; use IDs and look up state in Redis.
- Set bot commands via `bot.api.setMyCommands` once on deploy. Updates Telegram's `/` autocomplete UI.
- Privacy mode (default ON) means the bot only sees commands and messages mentioning it. Disable only if you need to read all group messages, and disclose it.

## Recent significant changes
- 2026-04-28: Scaffolded. Locked: grammY over node-telegram-bot-api (modern, ESM, types), webhook over polling (scale), Redis for conversation state.

## Next session: start here
1. Talk to @BotFather. Create bot. Save `TELEGRAM_BOT_TOKEN`.
2. Set commands: `/start`, `/help`, plus your domain-specific ones.
3. Implement `/start` handler. Test via DM with the bot.
4. Set webhook to ngrok URL during dev. Confirm Telegram fires it.
5. Deploy to prod, repoint webhook to prod URL.