f743a6749c
- Full Telegram bot implementation for Lightning Jackpot - Commands: /start, /buy, /tickets, /wins, /address, /jackpot, /help - Lightning invoice generation with QR codes - Payment polling and confirmation notifications - User state management (Redis/in-memory fallback) - Group support with admin settings panel - Configurable draw announcements and reminders - Centralized messages for easy i18n - Docker configuration included
147 lines
4.0 KiB
Markdown
147 lines
4.0 KiB
Markdown
# Lightning Jackpot Telegram Bot ⚡🎰
|
|
|
|
A Telegram bot for the Lightning Jackpot lottery system. Users can buy tickets, check their tickets and wins, and receive instant notifications - all through Telegram!
|
|
|
|
## Features
|
|
|
|
- 🎟 **Buy Tickets** - Quick buttons for 1, 2, 5, 10 tickets or custom amounts
|
|
- 💸 **Lightning Payments** - Generate and pay Lightning invoices directly in chat
|
|
- 📱 **QR Codes** - Visual QR codes for easy wallet scanning
|
|
- 🔔 **Real-time Updates** - Automatic payment confirmation notifications
|
|
- 🧾 **View Tickets** - See all your ticket purchases and their status
|
|
- 🏆 **Track Wins** - View your winning history and payouts
|
|
- ⚡ **Lightning Address** - Manage your payout address
|
|
|
|
## Prerequisites
|
|
|
|
- Node.js 18+
|
|
- Telegram Bot Token (from [@BotFather](https://t.me/BotFather))
|
|
- Lightning Jackpot Backend API running
|
|
|
|
## Installation
|
|
|
|
1. Clone the repository and navigate to the bot directory:
|
|
```bash
|
|
cd telegram_bot
|
|
```
|
|
|
|
2. Install dependencies:
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
3. Create environment file:
|
|
```bash
|
|
cp env.example .env
|
|
```
|
|
|
|
4. Configure your `.env` file:
|
|
```env
|
|
TELEGRAM_BOT_TOKEN=your_bot_token_here
|
|
API_BASE_URL=http://localhost:3000
|
|
FRONTEND_BASE_URL=http://localhost:3001
|
|
```
|
|
|
|
## Development
|
|
|
|
Run the bot in development mode with auto-reload:
|
|
```bash
|
|
npm run dev:watch
|
|
```
|
|
|
|
Or run once:
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
## Production
|
|
|
|
Build and run:
|
|
```bash
|
|
npm run build
|
|
npm start
|
|
```
|
|
|
|
## Docker
|
|
|
|
Build the image:
|
|
```bash
|
|
docker build -t lightning-lotto-telegram-bot .
|
|
```
|
|
|
|
Run the container:
|
|
```bash
|
|
docker run -d \
|
|
--name telegram-bot \
|
|
-e TELEGRAM_BOT_TOKEN=your_token \
|
|
-e API_BASE_URL=http://backend:3000 \
|
|
-e FRONTEND_BASE_URL=http://frontend:3001 \
|
|
lightning-lotto-telegram-bot
|
|
```
|
|
|
|
## Commands
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `/start` | Begin using the bot |
|
|
| `/menu` | Show main menu |
|
|
| `/buy` | Buy lottery tickets |
|
|
| `/tickets` | View your tickets |
|
|
| `/wins` | View your past wins |
|
|
| `/address` | Update Lightning Address |
|
|
| `/help` | Help & information |
|
|
|
|
## Architecture
|
|
|
|
```
|
|
src/
|
|
├── config/ # Configuration management
|
|
├── handlers/ # Command and callback handlers
|
|
│ ├── start.ts # /start command
|
|
│ ├── buy.ts # Ticket purchase flow
|
|
│ ├── tickets.ts # View tickets
|
|
│ ├── wins.ts # View wins
|
|
│ ├── address.ts # Lightning address management
|
|
│ ├── help.ts # Help command
|
|
│ └── menu.ts # Menu handling
|
|
├── services/
|
|
│ ├── api.ts # Backend API client
|
|
│ ├── state.ts # User state management (Redis/in-memory)
|
|
│ ├── qr.ts # QR code generation
|
|
│ └── logger.ts # Logging service
|
|
├── types/ # TypeScript type definitions
|
|
├── utils/
|
|
│ ├── format.ts # Formatting utilities
|
|
│ └── keyboards.ts # Telegram keyboard builders
|
|
└── index.ts # Main entry point
|
|
```
|
|
|
|
## State Management
|
|
|
|
The bot uses Redis for persistent state management when available. If Redis is not configured, it falls back to in-memory storage (not recommended for production).
|
|
|
|
User states:
|
|
- `idle` - Default state, browsing menu
|
|
- `awaiting_lightning_address` - Waiting for user to enter Lightning Address
|
|
- `awaiting_ticket_amount` - Waiting for custom ticket amount
|
|
- `awaiting_invoice_payment` - Polling for payment
|
|
- `updating_address` - Updating Lightning Address
|
|
|
|
## Environment Variables
|
|
|
|
| Variable | Description | Default |
|
|
|----------|-------------|---------|
|
|
| `TELEGRAM_BOT_TOKEN` | Telegram Bot API token | Required |
|
|
| `API_BASE_URL` | Backend API URL | `http://localhost:3000` |
|
|
| `FRONTEND_BASE_URL` | Frontend URL for ticket links | `http://localhost:3001` |
|
|
| `REDIS_URL` | Redis connection URL | Optional |
|
|
| `MAX_TICKETS_PER_PURCHASE` | Maximum tickets per purchase | `100` |
|
|
| `PAYMENT_POLL_INTERVAL_MS` | Payment polling interval | `5000` |
|
|
| `PAYMENT_POLL_TIMEOUT_MS` | Payment polling timeout | `900000` |
|
|
| `LOG_LEVEL` | Logging level | `info` |
|
|
|
|
## License
|
|
|
|
MIT
|
|
|