WhatsApp Bulk Messenger

A Node.js application that allows sending bulk messages via WhatsApp Web API. The application provides a web interface for managing contacts, sending messages, and uploading files to multiple recipients.

Features

Authentication & Connection

• WhatsApp Web integration using QR code authentication
• Automatic reconnection handling
• Connection status monitoring

Contact Management

• Import contacts directly from WhatsApp
• Real-time contact search functionality
• Manual phone number addition with validation
• Contact list upload via JSON file
• Duplicate number prevention
• Contact filtering and sorting

Message Sending

• Bulk message sending capabilities
• File attachment support (images, documents)
• Delayed message sending to avoid spam detection
• Progress tracking for message sending
• Support for formatted messages

Phone Number Validation

• International format validation
• Automatic format checking
• Real-time validation feedback
• Error messaging for invalid numbers

User Interface

• Clean, responsive design
• Real-time search in contacts
• Intuitive contact management
• Progress and status indicators
• File upload interface
• Error handling and user feedback

Prerequisites

• Node.js (v14 or higher)
• npm (Node Package Manager)
• Modern web browser
• Active WhatsApp account

Installation

1. Clone the repository:

git clone [repository-url]
cd whatsapp-bulk-messenger

2. Install dependencies:

npm install

3. Create a .env file in the root directory:

touch .env

4. Add required environment variables to .env:

PORT=3000

Project Structure

project/
├── public/
│   ├── index.html     # Main HTML file
│   ├── styles.css     # Stylesheet
│   └── script.js      # Client-side JavaScript
├── uploads/           # Temporary storage for uploaded files
├── server.js         # Main application file
├── package.json
└── README.md

Dependencies

• express - Web application framework
• whatsapp-web.js - WhatsApp Web API client
• qrcode - QR code generation
• dotenv - Environment variable management
• multer - File upload handling
• body-parser - Request body parsing

Usage

Starting the Application

1. Start the server:

node server.js

2. Open your web browser and navigate to:

http://localhost:3000

Connecting WhatsApp

1. Scan the QR code with your WhatsApp mobile app:
   • Open WhatsApp on your phone
   • Go to Settings > WhatsApp Web/Desktop
   • Scan the displayed QR code

Managing Contacts

1. Import WhatsApp Contacts:

   • Click "Get WhatsApp Contacts"
   • Use the search bar to filter contacts
   • Click "Add" button next to contacts you want to message

2. Manual Number Addition:

   • Enter the phone number in international format (without '+')
   • System will validate the number automatically
   • Click "Add Number" or press Enter

3. Upload Contact List:

   • Prepare a JSON file with contacts
   • Click "Upload Contacts" and select your file

4. Search Contacts:

   • Use the search bar above the contact list
   • Search works with both names and phone numbers
   • Results update in real-time
   • Press Escape to clear search

Sending Messages

1. Select recipients (any combination of):

   • Imported WhatsApp contacts
   • Manually added numbers
   • Uploaded contact list

2. Compose your message

3. Optionally attach a file

4. Click "Send Message"

Phone Number Format

The application accepts phone numbers in international format:

• Numbers should be entered without the '+' symbol
• Only digits are allowed (no spaces or special characters)
• Length should be between 10 and 15 digits
• Examples:
  • US number: 12125550123
  • UK number: 441234567890
  • German number: 4915123456789

JSON Contact File Format

The contact JSON file should follow this structure:

[
    {
        "name": "John Doe",
        "phone": "12125550123",
        "messenger": "WhatsApp",
        "gare": "Location"
    }
]

Security Considerations

• The application stores WhatsApp session data temporarily
• No message content or phone numbers are permanently stored
• Files are deleted after sending
• It's recommended to run the application on a secure network

Limitations

• Message sending rate is limited to prevent blocking
• File attachments size is limited to 16MB
• WhatsApp Web connection must remain active
• Only one WhatsApp account can be connected at a time

Troubleshooting

Common Issues

1. QR Code not scanning:

   • Ensure your phone has a stable internet connection
   • Try refreshing the page
   • Make sure WhatsApp is up to date on your phone

2. Messages not sending:

   • Check the WhatsApp connection status
   • Verify phone number format
   • Ensure the delay between messages is sufficient

3. Contact loading issues:

   • Ensure WhatsApp is properly connected
   • Check your internet connection
   • Try refreshing the contacts list

4. Search not working:

   • Ensure contacts are loaded
   • Try clearing the search and searching again
   • Check for special characters in search

Development

Adding New Features

1. Server-side changes go in server.js
2. Client-side logic goes in public/script.js
3. UI changes go in public/index.html
4. Styling changes go in public/styles.css

Best Practices

• Keep the code modular
• Add error handling
• Include user feedback
• Update documentation
• Test thoroughly

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For additional support:

• Check the WhatsApp Web API documentation
• Review the issue tracker
• Contact the project maintainers