wa-bulk-web

A Bulk WhatsApp sender using Puppeteer and whatsapp-web.js. This tool automates sending messages to a list of contacts from a CSV or JSON file.

Disclaimer: This tool is for educational and testing purposes only. Automated bulk messaging can lead to your WhatsApp account being banned. Use responsibly and at your own risk.

Installation

1. Clone the repository (or download the source code).
2. Install dependencies:

   npm install

Usage

You can run the tool directly using node or link it to run as a command.

# Basic usage
node bin/wa-bulk-web.js --file contacts.csv --number-field phone --message-field message --confirm

Options

| Option | Description | Default | | :--- | :--- | :--- | | -f, --file <path> | Required. Path to CSV or JSON input file. | - | | -n, --number-field <field> | Field name in the file containing the phone number. | (Prompts user if omitted) | | -m, --message-field <field> | Field name in the file containing the message. | (Prompts user if omitted) | | --media <path> | Path to a media file (image, video, PDF, etc.) to attach to the message. | - | | --confirm | Required. Acknowledge risks. | false | | --dry-run | Simulate sending without actually sending messages. | false | | --rate <ms> | Delay between messages in milliseconds. | 5000 | | --randomize-delay | Randomize the delay by ±20% to behave more human-like. | false | | --scan | (Implicit) The first run will generate a QR code in the terminal to scan with WhatsApp. | - | | --logout | Clear the saved session and exit. | - |

Input File Formats

JSON:

[
  { "name": "Alice", "phone": "1234567890", "msg": "Hello Alice!" },
  { "name": "Bob", "phone": "0987654321", "msg": "Hello Bob!" }
]

CSV:

name,phone,msg
Alice,1234567890,Hello Alice!
Bob,0987654321,Hello Bob!

Templating

You can use Mustache templates in your messages. The column headers in your CSV/JSON become the keys.

Example CSV:

name,phone
Alice,1234567890

Command:

# If your message field in the code was fixed, but here the tool expects a message field in the row.
# To use templates effectively, your 'message' field in the CSV should contain the template, OR you can't currently pass a static message via CLI.
# The tool currently expects the message to be IN the file row.

Note: The current implementation expects the message content to be present in one of the fields of your input file. You can embed templates like Hello {{name}} strictly inside that field.

sending Media

To send an image or file along with the text message:

node bin/wa-bulk-web.js --file contacts.json --media ./images/flyer.png --confirm

The message text from your file will be sent as the caption for the image.

Audit Logs

Every run generates a log file in the logs/ directory containing the status of each message sent.