WhatsApp Blast

A Node.js application for sending WhatsApp messages to multiple recipients from CSV files using the whatsapp-web.js library.

Features

• Authentication via QR code scanning
• CSV import functionality for sending messages to contacts
• Automatic phone number formatting
• Configurable delay between messages
• Check if numbers are registered on WhatsApp before sending
• Message personalization with {name} placeholder
• Parallel message processing with controlled concurrency
• Modern JavaScript features (ES Modules)
• Automatic application exit when processing is complete
• Default contacts file for simplified usage
• Support for multiline messages

Prerequisites

• Node.js (v22 or later)
• PNPM package manager
• A phone with WhatsApp installed and connected to the internet

Installation

1. Clone this repository
2. Install dependencies:

   pnpm install
   

3. Create a .env file (or use the existing one) with the following variables:

   DELAY_BETWEEN_MESSAGES=3000
   

4. Create your contacts file by copying the sample:

   cp sample.contacts.csv contacts.csv
   

   Then edit contacts.csv with your actual contacts. This file is git-ignored for privacy.

Usage

Sending messages from a CSV file

The simplest way is to just specify the message (the app will use contacts.csv by default):

node src/index.js "Hello {name}, this is a test message"

Or use the start script:

pnpm start "Hello {name}, this is a test message"

If you want to use a different CSV file, you can specify it as the first argument:

node src/index.js path/to/other/file.csv "Hello {name}, this is a test message"

Sending Multiline Messages

Method 1: Edit the source code (Recommended)

The most reliable way to send multiline messages is to edit the src/csv-blast.js file directly. You can uncomment and modify the example there:

// In src/csv-blast.js, uncomment and edit this section:
const messageText = `Hello {name}! 👋

This is a multiline message with proper formatting.
It supports multiple paragraphs and special characters.

Thanks! 🙌
`

Method 2: Using \n escapes in the command line

For simpler multiline messages, use the \n escape sequence in your command:

pnpm start "Hello {name}!\nThis is a second line.\nThis is a third line."

This method correctly produces line breaks in WhatsApp.

Method 3: Using a message file (Important note about newlines)

Note: When reading from text files, you may encounter issues with Windows-style line endings (\r\n). The content might be sent with literal \r\n characters instead of actual line breaks.

If you want to try using a message file:

1. Create a message.txt file with your content
2. Use the following command:

   # PowerShell
   pnpm start "$(Get-Content -Raw message.txt)"

However, this may not work correctly with line breaks. For reliable multiline messages, use Method 1 or Method 2.

First-time setup

1. When you first run the application, you'll see a QR code in the terminal
2. Open WhatsApp on your phone
3. Tap Menu or Settings and select WhatsApp Web
4. Scan the QR code displayed in the terminal
5. Once authenticated, you'll see "WhatsApp client is ready!" in the console
6. The application will process the CSV file, send messages, and exit automatically when complete

CSV File Format

The CSV file should have a header row with a column for names and a column for phone numbers. The application will try to detect the phone number column automatically by looking for column names containing 'phone', 'mobile', or 'tel'.

Example CSV format:

name,phone
John Doe,+6281234567890
Jane Smith,62812345678
Robert,6281234567891
Mike Johnson,081234567892

You can use the {name} placeholder in your message to personalize it with the contact's name.

A sample file (sample.contacts.csv) is provided which you should copy to contacts.csv and edit with your actual contacts.

Phone Number Format

The application will automatically format phone numbers:

• Non-digit characters will be removed
• If a phone number doesn't start with a country code (1, 62, 44), it will default to Indonesia code (62)

Performance Features

This application takes advantage of Node.js v22 features to improve performance:

• Parallel message sending with controlled concurrency
• Modern ES modules for better code organization
• Native timers/promises for delay management
• Stream-based CSV parsing with async iterators

Security Considerations

• This application is designed for personal or authorized use only
• Do not use this to send spam or unsolicited messages
• Sending too many messages in a short time may result in your WhatsApp account being banned
• contacts.csv is excluded from git to protect your contact privacy

Credits

This project is built with the help of Cursor Agent.

License

MIT