WhatsApp Bot

A feature-rich WhatsApp bot built with whatsapp-web.js designed for university study groups. Manage notes, set reminders, play games, chat with AI, and more!

Features

👑 Admin Management

• !makemeadmin - First-time setup to become the first admin
• !addadmin @user - Add a user as bot admin
• !removeadmin @user - Remove a user from admins
• !admins - List all bot admins
• !allowgroup [alias] - Allow current group to use the bot with optional unique alias
• !disallowgroup - Remove current group from allowed list
• !groups - List all allowed groups
• !status [quick] - Display bot status, system info, and runtime statistics
• !pause - Pause the bot (stop responding to commands except !resume)
• !resume - Resume the bot after pausing
• !delete - Delete a message (reply to message to delete)
• !relay -> <destination> <message> - Send message to group (by alias) or person (by phone)
  • Send to group: !relay -> unimates Hello everyone!
  • Send to phone: !relay -> 8801940289890 Hey there
  • With mentions: !relay -> unimates Hello @8801940289890, how are you?
  • Forward message: !relay -> unimates (reply to a message)
• !broadcast <message> - Send a message mentioning each group member individually
  • In current group: !broadcast Important update!
  • To remote group: !broadcast -> unimates Message

🤖 AI Chat (OpenRouter)

• !ai <question> - Ask AI anything (powered by OpenRouter with automatic model fallback)
• !aiclear - Clear conversation history for this chat
• !aistatus - Check AI service status and configuration

Note: AI has a rate limit of 3 messages per minute per user. The bot remembers the last 10 exchanges for context.

🔍 Search

• !google <query> - Search Google and get instant results
• !wiki <topic> - Search Wikipedia for information

📝 Notes & Resources

• !addnote <title> | <content> [| tags] - Save a note with optional tags
• !notes [search] - List all notes or search
• !note <id or title> - View a specific note
• !delnote <id or title> - Delete a note

⏰ Reminders

• !remind <time> | <message> [| recurring] - Set a one-time or recurring reminder
  • Time formats: 30m, 2h, 1d, 10:30, 10:30 PM, 2026-02-01 09:00
  • Recurring options: hourly, daily, weekly, monthly
  • Examples:
    • !remind 30m | Take a break
    • !remind 09:00 | Stand-up meeting | daily
    • !remind 10:00 | Weekly review | weekly
• !reminders - List all active reminders
• !delremind <id> - Delete a reminder

🎮 Fun & Games

• !flip - Flip a coin
• !roll [dice notation] - Roll dice (e.g., !roll 2d6, !roll d20)
• !pick <option1>, <option2>, ... - Random picker
• !8ball <question> - Ask the magic 8-ball
• !pickmember - Randomly pick a group member
• !rate <thing> - Rate something 0-10
• !poll <question> | <option1>, <option2>, ... - Create a poll
• !trivia - Get a trivia question
• !answer <answer> - Check your trivia answer
• !joke - Get a random joke
• !truthordare [truth/dare] - Play Truth or Dare
• !roast [@mention] - Get a playful roast
• !motivate [random] - Get a motivational quote
• !guessword - Start a word guessing game with AI hints
• !guess <word> - Make a guess in the word game
• !hint - Get another hint in the word game
• !giveup - Give up and reveal the word

� Islamic Features

Prayer times and fasting support with automated reminders

Prayer Times Commands

• !prayertimes [date] [city] [country] - Get prayer times for a specific date and location
  • Aliases: !pt, !prayer, !salah, !namaz
  • Examples: !prayertimes, !pt tomorrow London UK, !prayer 15-03-2026 Dubai UAE
• !fasting [date] [city] [country] - Get Sehri and Iftar times (year-round fasting support)
  • Aliases: !sehri, !iftar, !fast, !roza
  • Examples: !fasting, !sehri today Makkah Saudi Arabia, !iftar tomorrow
• !islamictimes [date] [city] [country] - Get complete Islamic schedule (prayers + fasting)
  • Aliases: !it, !times, !schedule
  • Examples: !islamictimes, !it today Dubai UAE, !times 2026-03-20 London UK
• !schedulerstatus - Check Islamic scheduler status (admin only)
  • Aliases: !ss, !islamicstatus

Automated Features

📅 Daily 12:00 AM Broadcast

• Complete Islamic schedule for the day (pinned for 24 hours)
• Includes prayer times with time ranges AND fasting times
• Automatically sent to all allowed groups

🕌 Prayer Time Notifications (when enabled)

• Start notification when each prayer time begins (Fajr, Dhuhr, Asr, Maghrib, Isha)
• End notification when each prayer time ends (not warnings - actual end times)
• Shows time range for each prayer (e.g., "Fajr: 05:05 - 06:14")
• Prayer time ranges:
  • Fajr: Until 1 min before Sunrise
  • Dhuhr: Until 1 min before Asr
  • Asr: Until 1 min before Sunset
  • Maghrib: Until 1 min before Isha
  • Isha: Until Sehri end time (next day)
• Broadcasts to all allowed groups

🌙 Fasting Reminders (when enabled, works year-round)

• 1 hour before Sehri ends: Reminder with time remaining (mentions everyone)
• Sehri end alert: Notification when Sehri time ends (mentions everyone)
• Midday motivation: Halfway reminder with motivational message (optional)
• 1 hour before Iftar: Iftar approaching reminder
• Iftar start: Notification when it's time to break fast

🌍 Location Support

• Default location: Dhaka, Bangladesh (configurable in src/config/prayerTimes.ts)
• Optional city parameter: Look up times for any city worldwide
• Supports both coordinate-based and city-based lookups

�🔧 Utilities

• !help [command | all] - Show help for all or specific command
  • !help all (admin only) - Show all commands including admin commands
• !intro - Bot introduces itself
• !ping - Check if bot is online
• !everyone [message] - Tag all group members
  • In current group: !everyone Meeting time!
  • To remote group: !everyone -> unimates Check this
• !groupinfo - Show group information
• !botinfo - Show bot information
• !sticker - Convert image/video to sticker
• !quote - Get info about a quoted message

Project Structure

src/
├── index.ts              # Main entry point
├── config/
│   ├── index.ts          # Bot configuration
│   └── prayerTimes.ts    # Prayer times API configuration
├── types/
│   ├── index.ts          # TypeScript types
│   └── wawebjs.ts        # whatsapp-web.js type extensions
├── handlers/
│   ├── index.ts          # Handler exports
│   └── commandHandler.ts # Command parsing and execution
├── commands/
│   ├── index.ts          # Command aggregation
│   ├── admin.ts          # Admin commands
│   ├── ai.ts             # AI chat commands
│   ├── broadcast.ts      # Broadcast commands
│   ├── fun.ts            # Fun & games commands
│   ├── notes.ts          # Notes commands
│   ├── prayerTimes.ts    # Prayer times & fasting commands
│   ├── reminders.ts      # Reminder commands
│   ├── search.ts         # Search commands
│   └── utility.ts        # Utility commands
├── services/
│   ├── index.ts          # Service exports
│   ├── ai.ts             # AI provider integration (OpenRouter)
│   ├── botStats.ts       # Bot statistics tracking
│   ├── conversationContext.ts # Conversation history management
│   ├── discordWebhook.ts # Discord notifications
│   ├── islamicScheduler.ts # Islamic prayer & fasting scheduler
│   ├── logger.ts         # Logging service
│   └── prayerTimes.ts    # Prayer times API service
└── utils/
    ├── index.ts          # Utility exports
    ├── permissions.ts    # Permission checking
    ├── rateLimit.ts      # Rate limiting
    └── storage.ts        # Data persistence
data/                     # Created at runtime
├── admins.json           # Admin and group permissions
├── chats/                # Per-chat data (notes, reminders)
└── conversations/        # AI conversation history

Setup

1. Install dependencies:

   pnpm install

2. Create a .env file with your configuration:

   # Bot phone number (required for pairing)
   BOT_PHONE_NUMBER=your_phone_number
   
   # Launch browser in headless mode (optional, default: true)
   LAUNCH_HEADLESS=true
   
   # AI Configuration (at least one provider required for AI features)
   # OpenRouter (Primary)
   OPENROUTER_API_KEY=your_openrouter_key
   OPENROUTER_API_KEY_BKUP=your_backup_openrouter_key  # Optional backup key
   OPENROUTER_MODEL=openai/gpt-oss-120b:free  # Optional, default shown
   OPENROUTER_BASE_URL=https://openrouter.ai/api/v1  # Optional
   
   # Upstage (Fallback)
   UPSTAGE_API_KEY=your_upstage_key  # Optional fallback provider
   UPSTAGE_MODEL=solar-pro3  # Optional, default shown
   UPSTAGE_BASE_URL=https://api.upstage.ai/v1  # Optional
   
   # Optional: Discord webhook for status notifications
   DISCORD_WEBHOOK_URL=your_webhook_url
   
   # Islamic Features (Optional)
   ENABLE_PRAYER_TIMES=true           # Prayer time notifications
   ENABLE_FASTING_TIMES=true          # Fasting reminders (year-round)
   ENABLE_MIDDAY_MOTIVATION=true      # Midday motivational messages

3. Build and run:

   pnpm dev

4. Scan the QR code with WhatsApp or use the pairing code.

5. Send !makemeadmin in any chat to become the first admin.

Configuration

Edit src/config/index.ts to customize:

• prefix - Command prefix (default: !)
• botName - Bot display name (default: Sudo bot)
• dataDir - Data storage directory (default: ./data)
• timezone - Default timezone for reminders (default: Asia/Dhaka)
• launchHeadless - Launch browser in headless mode (default: true)

AI Configuration

The bot supports multiple AI providers with automatic fallback:

1. Primary Provider: OpenRouter (default model: openai/gpt-oss-120b:free)
2. Backup Provider: OpenRouter with secondary API key (same model)
3. Fallback Provider: Upstage (default model: solar-pro3)

If the primary provider fails, the bot automatically tries the backup key, then falls back to Upstage. You can customize models using environment variables (OPENROUTER_MODEL, UPSTAGE_MODEL).

The AI maintains conversation context per chat, remembering the last 10 exchanges.

Adding New Commands

1. Create a command file in src/commands/ or add to an existing one
2. Define your command using the Command interface:

const myCommand: Command = {
  name: "mycommand",
  aliases: ["mc"],
  description: "Description for help",
  usage: "<required> [optional]",
  examples: ["mycommand hello"],
  category: "utility",
  adminOnly: false,
  groupOnly: false,
  handler: async (ctx) => {
    const { message, args, rawArgs, chat, client, isAdmin, senderId } = ctx;
    await message.reply("Hello!");
  },
};

3. Export and add to the command array
4. Import in src/commands/index.ts

Permissions

• Admins: Can use admin-only commands, manage the bot
• Allowed Groups: Groups where the bot responds to commands
• Direct Messages: Only admins can use the bot in DMs

Group Aliases

Group aliases allow you to reference groups by memorable names instead of long WhatsApp IDs:

1. Assign an alias when allowing a group:

   !allowgroup unimates
   

2. Use the alias in relay, broadcast, and everyone commands:

   !relay unimates Hello everyone!
   !broadcast Important update -> unimates
   !everyone Check this out -> unimates
   

3. Alias rules:

   • Must be unique across all allowed groups
   • Can only contain letters, numbers, and underscores
   • Case-sensitive

4. Legacy compatibility: Groups allowed without aliases still work with their WhatsApp IDs

Dependencies

• whatsapp-web.js - WhatsApp Web API
• OpenAI - OpenRouter integration
• cheerio - HTML parsing for web scraping
• dotenv - Environment variable management

License

MIT