Telegram Bot Demo

Serverless Telegram bot built with:

• @effect-ak/tg-bot — Type-safe Telegram Bot API client with fluent builder, long polling, and webhook handler
• effortless-aws — Code-first AWS Lambda deployment framework

Features

• 🎯 Type-safe Telegram Bot API interactions
• 🚀 Serverless deployment with AWS Lambda + API Gateway
• ⚡ Fast deployment with effortless-aws (~5-10s)
• 🔒 Bot token in AWS SSM Parameter Store
• 📊 User message stats in DynamoDB (single-table design)
• 🌐 Telegram Mini App page served via CloudFront + S3

Try It Live

The bot is already deployed on AWS Lambda:

👉 @kondaurov_effect_tg_bot

Available commands:

• /start — Welcome message with fire effect
• /help — GitHub repository link
• /typescript — Random TypeScript fact
• /echo — Echoes the message in JSON format
• /random — Sends a soccer ball dice

Prerequisites

• Node.js 18+ and pnpm
• AWS account with configured credentials (aws configure)
• Telegram Bot Token (get one from @BotFather)

Local Development

1. Install dependencies:

pnpm install

2. Create a .env file:

BOT_TOKEN=your_telegram_bot_token

3. Run the bot locally (long polling):

pnpm dev

Deployment to AWS

1. Store bot token in AWS SSM Parameter Store

Create a SecureString parameter:

• Dev: /effect-tg-bot/dev/bot-token
• Prod: /effect-tg-bot/prod/bot-token
• Region: eu-west-1

2. Deploy

# Dev stage
pnpm deploy

# Prod stage
pnpm deploy:prod

Deployment provisions:

• Lambda for the webhook handler (POST /webhook)
• Lambda for the setup endpoint (GET /setup-webhook)
• DynamoDB table for user stats
• S3 + CloudFront for the Mini App static page
• IAM roles, SSM access, and API Gateway

3. Configure the Telegram webhook

Call the deployed setup endpoint — it registers the webhook URL and bot commands in one shot:

curl https://your-api-gateway-url.amazonaws.com/setup-webhook

Or use the helper scripts:

WEBHOOK_URL=https://your-api-gateway-url.amazonaws.com/webhook pnpm webhook:set
pnpm webhook:info

4. View logs

pnpm logs

5. Destroy resources

pnpm destroy

Project Structure

src/
├── bot.ts              # Bot commands and handlers (defineBot)
├── polling.ts          # Long polling for local dev (runBot)
├── webhook.ts          # Lambda webhook handler (defineApi builder)
├── setup-webhook.ts    # Lambda endpoint that registers webhook + commands
├── db.ts               # DynamoDB user-stats table (defineTable)
├── webapp.ts           # Mini App static site (defineStaticSite)
└── webapp/app.html     # Mini App page

effortless.config.ts    # Deployment configuration

How It Works

Local Development

Uses long polling via runBot from @effect-ak/tg-bot.

Production (AWS Lambda)

Telegram sends updates directly to the Lambda via API Gateway webhook. The webhook handler is built with the defineApi builder from effortless-aws, with typed deps, SSM secrets, and a single-table DynamoDB design for user stats.

Configuration

Edit effortless.config.ts to customize:

• AWS region
• Lambda memory and timeout
• Stage names
• Handler discovery paths

Learn More

• @effect-ak/tg-bot
• effortless-aws
• Telegram Bot API

License

MIT