🤖 BotWA - WhatsApp Bot

A powerful and extensible WhatsApp bot built with TypeScript and the Baileys library. This bot allows you to automate interactions on WhatsApp with a modular command system and plugin architecture. Fully compatible with Node.js runtime

✨ Features

• 🔧 Modular Command System: Easy to add and manage commands through a plugin system
• 📱 Multi-device Support: Works with WhatsApp's multi-device protocol
• 👥 Group Management: Welcome messages and group participation tracking
• 🔐 Permission System: Owner-only, group-only, and private chat commands
• 🔄 File Watching: Automatically reloads commands when plugin files are modified
• 📎 Media Handling: Support for processing various media types
• 📚 Message History: Stores and processes historical messages

🧰 Prerequisites

• 🟢 Node.js (v18 or higher)
• 📦 npm or yarn package manager
• 📱 WhatsApp account with a verified phone number

🚀 Installation

1. Clone the repository:

   git clone <repository-url>
   cd botwa

2. Install dependencies:

   npm install

⚙️ Configuration

1. Create a .env file in the root directory (if not already present) and set the following variables:

   OWNER=6281910094713  # Your phone number in international format
   isSelf=true          # Set to true to enable self-mode (only respond to owner)
   

2. Make sure to replace OWNER with your actual phone number in international format without the + sign.

🎯 Usage

For Development:

npm run dev

For Production:

1. Build the project:

   npm run build

2. Start the bot:

   npm start

3. On first run, the bot will prompt you to enter your phone number and provide a pairing code. Follow the instructions to connect your WhatsApp account.

4. The bot will generate authentication credentials in the baileys_auth_info/ directory. These files will be used for subsequent logins.

🛠️ Commands

The bot uses a command system with the following syntax:

• Commands start with !, /, or .
• Example: !menu, /help, .list

Available Commands

• 📋 Menu Command: Displays all available commands

  • Usage: !menu, !help, or !list
  • Shows commands organized by category with descriptions and usage information

• 🔍 Category-specific Menu: Display commands for a specific category

  • Usage: !menu [category]
  • Example: !menu info

Adding Custom Commands

The bot supports a plugin system for adding custom commands:

1. Create a new TypeScript file in the src/plugins/ directory

2. Use the command registration system:

   import cmd, { type CommandContext } from "../commands/map";
   
   cmd.add({
     name: "hello",
     alias: ["hi", "greeting"],
     category: ["general"],
     desc: "Sends a greeting message",
     async run({ m }: CommandContext) {
       m.reply("Hello! How are you?");
     }
   });

3. The bot automatically detects and loads new commands when the file is saved (thanks to the file watcher).

Running Code Without Commands (Using Middleware)

The bot also supports middleware functionality that allows you to execute code for every message received, regardless of whether it's a command or not. This is particularly useful for:

• Auto-replying to specific keywords or phrases
• Logging all messages
• Tracking user activity
• Implementing automatic responses based on content

To use middleware functionality:

1. Create a new file in the src/plugins/ directory (e.g., auto-reply.ts)

2. Use the middleware property instead of the run property:

   import cmd, { type CommandContext } from "../commands/map";
   
   cmd.add({
     middleware: async ({ m, sock }: CommandContext) => {
       // This function runs for every received message
       const messageText = m.body.toLowerCase();
       
       // Example: Auto-reply to messages containing "hello"
       if (messageText.includes("hello")) {
         m.reply("Hi there! I received your message.");
       }
       
       // Example: Log all messages to console
       console.log(`Received message: ${m.body} from ${m.sender}`);
     }
   });

3. The middleware function will execute for every incoming message, whether it's a command or not

4. Unlike the run property which only executes when the command is specifically called, middleware runs on every message

5. Remember that middleware runs frequently, so optimize your code for performance

🔒 Permissions System

Commands can have different permission levels:

• 👑 Owner-only: Only the number specified in OWNER environment variable can use
• 👥 Group-only: Only works in group chats
• 💬 Private-only: Only works in private messages
• 🤖 Self-only: Only responds to messages from the bot itself

📁 Project Structure

botwa/
├── index.ts              # Main entry point
├── .env                  # Environment variables
├── .gitignore
├── package.json
├── README.md
├── tsconfig.json         # TypeScript configuration
├── baileys_auth_info/    # Authentication credentials
├── node_modules/
├── dist/                 # Compiled JavaScript files (after build)
└── src/
    ├── data-store.ts     # Data persistence layer
    ├── commands/
    │   ├── handler.ts    # Command processing logic
    │   ├── map.ts        # Command registry interface
    │   └── register.ts   # Command loading and watching
    ├── plugins/          # Command plugins (.ts files)
    └── utils/
        ├── msg.ts        # Message processing utilities
        └── fmt.ts        # Message formatting utilities

🌐 Environment Variables

• OWNER: WhatsApp number in international format (without +) of the bot owner
• isSelf: When set to true, bot only responds to owner's commands

🧑‍💻 Development

To contribute or modify the bot:

1. Make changes to the source code in the src/ directory
2. For development, use npm run dev to run with automatic reloading
3. For plugin changes, the bot automatically reloads when you save
4. For core changes, restart the bot to see the changes

🏗️ Building for Production

To compile the TypeScript code to JavaScript:

npm run build

This will create a dist/ directory with the compiled JavaScript files.

📚 Common Commands in the Bot

The bot comes with a default command system. Use !menu, !help, or !list to see all available commands once the bot is running.

🐛 Troubleshooting

• If you get authentication errors, delete the baileys_auth_info/ directory and restart the bot to re-authenticate
• Make sure your phone number is in international format in the .env file
• Check that the bot has proper permissions for the actions you're trying to perform
• For development, use npm run dev for easier debugging

🤝 Community & Support

Join our WhatsApp group for discussions, support, and updates:

Stay updated with other projects by following our WhatsApp channel:

🖥️ Hosting Your Bot

Looking for reliable hosting for your WhatsApp bot? Check out pwcraft cloud for affordable and stable VPS solutions perfect for running your bot 24/7:

📄 License

This project is open source and available under the MIT License.