🌙 Telegram Quran Ayah Bot

A professional-grade NestJS Telegram bot that delivers daily Quran Ayahs with translations in multiple languages. Built with queue processing, scheduled tasks, and a clean architecture.

🌟 Features

• Daily Scheduled Ayah: Sends a random Quran Ayah every day at 9:00 AM
• Multi-Language Support:
  • 🇮🇷 Farsi (Persian)
  • 🇬🇧 English
• Smart Queue System: Bull-based queue for reliable message delivery
• Translation Support: Automatically fetches Ayah translations in selected language
• User Sessions: Maintains user language preferences
• Interactive UI: Inline buttons for easy navigation
• Error Handling: Comprehensive error handling and logging
• Monitoring: Queue statistics and health checks

🚀 Quick Start

Prerequisites

• Node.js 16+
• Redis Server (for queue processing)
• Telegram Bot Token (from @BotFather)

Installation

# Install dependencies
npm install

# Create .env file
cp .env.example .env

# Edit .env with your configuration
TELEGRAM_BOT_TOKEN=your_token_here
REDIS_HOST=localhost
REDIS_PORT=6379

Run Development

npm run start:dev

Run Production

npm run build
npm run start:prod

📁 Project Structure

src/
├── config/              # Configuration management
├── interfaces/          # TypeScript interfaces
├── modules/
│   ├── telegram/       # Telegram bot handlers and service
│   ├── quran/          # Quran API service and user management
│   ├── queue/          # Bull queue producers and consumers
│   └── scheduler/      # Cron job scheduling
├── services/           # Business logic services
├── app.module.ts       # Root module
└── main.ts            # Application entry point

🔧 Configuration

Environment Variables

# Telegram Configuration
TELEGRAM_BOT_TOKEN=your_bot_token

# Redis Configuration
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0

# Application Settings
NODE_ENV=development
LOG_LEVEL=debug

# Daily Ayah Schedule
SEND_AYAH_HOUR=9
SEND_AYAH_MINUTE=0

🎯 Usage

Start the Bot

/start

The bot will welcome you and ask to select language:

• 🇮🇷 Farsi
• 🇬🇧 English

Get a Random Ayah

After selecting language, the bot sends a random Ayah from the Quran with translation.

Send Another Ayah

Use the "Send Another Ayah" button to get another random Ayah.

Daily Broadcast

The bot automatically sends a random Ayah to all users every day at 9:00 AM (Tehran timezone).

🏗️ Architecture

Modules

Telegram Module

• Handles all Telegram interactions
• Command and callback query processing
• Message formatting

Quran Module

• Quran API integration
• Random Ayah selection
• Translation management

Queue Module

• Bull queue processing
• Job producers and consumers
• Retry logic with exponential backoff

Scheduler Module

• Daily broadcast scheduling
• Cron job management

📊 Queue System

The bot uses Bull (Redis-backed queue) for reliable message delivery:

• Job Priority: Daily broadcasts (priority 10), User requests (priority 5)
• Retry Policy: 3 attempts with exponential backoff
• Job Cleanup: Completed jobs automatically removed

Queue Job Structure

{
  chatId: number;
  language: 'fa' | 'en';
  type: 'daily' | 'user_requested';
  timestamp: number;
}

🌐 API Integration

The bot integrates with the Quran.com API:

• Endpoint: https://api.quran.com/api/v4
• Automatic Surah caching
• Translation support (Farsi & English)

🛡️ Error Handling

• Comprehensive error logging
• Graceful fallbacks
• Queue job retry mechanism
• User-friendly error messages

📝 Logging

// Service logging
Logger.log('Information message');
Logger.error('Error message', error);
Logger.debug('Debug message');
Logger.warn('Warning message');

🔍 Monitoring

Queue Statistics

# Returns queue statistics
- Total jobs
- Active jobs
- Delayed jobs
- Failed jobs
- Completed jobs

Health Checks

• Bot connectivity
• Redis connection
• Quran API availability

🚀 Deployment

Docker

FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm install --production

COPY dist ./dist

EXPOSE 3000

CMD ["npm", "run", "start:prod"]

Environment Setup

# Production
NODE_ENV=production
LOG_LEVEL=error
SEND_AYAH_HOUR=9
SEND_AYAH_MINUTE=0

🧪 Testing

npm run test
npm run test:watch
npm run test:cov

📦 Dependencies

• @nestjs/core - NestJS framework
• @nestjs/bull - Queue management
• @nestjs/schedule - Task scheduling
• telegraf - Telegram Bot API
• bull - Queue library
• axios - HTTP client
• redis - Redis client

🐛 Troubleshooting

Bot Not Receiving Messages

• Verify TELEGRAM_BOT_TOKEN is correct
• Check if Redis is running
• Review logs for connection errors

Queue Jobs Not Processing

• Ensure Redis is accessible
• Check Redis connection settings
• Review consumer logs

Missing Translations

• Verify Quran API is accessible
• Check language code mapping
• Ensure translation IDs are correct

📞 Support

For issues and questions:

1. Check the logs
2. Verify environment configuration
3. Review NestJS documentation

📄 License

MIT

👨‍💻 Author

Built with ❤️ by a Senior Backend Developer

---

Note: This bot follows production-grade best practices including:

• Clean architecture
• SOLID principles
• Comprehensive error handling
• Scalable queue system
• Type-safe implementation
• Professional logging