Simple WhatsApp Bot

Simple WhatsApp bot built with Express.js, featuring clean architecture and comprehensive API endpoints.

📑 Navigation

• 🚀 Installation
• 🔐 Authentication
• ➕ Adding a New Command
• 🌐 API Documentation
  • Health Check
  • Send Message
  • Get Group ID
• 🔧 API Parameters
• 📚 Documentation
• 🤝 Contributing
• 📄 License

GitAds Sponsored

🚀 Installation

1. Clone the repository:

   git clone https://github.com/nestorzamili/whatsapp-web-js.git
   cd whatsapp-web-js

2. Install dependencies:

   npm install

3. Create .env file:

   PORT=3000
   API_KEY=your_api_key_here

4. Start the application:

   npm start

5. Scan the QR code with your WhatsApp to authenticate

🔐 Authentication

All API endpoints require authentication via the x-api-key header.

Generate API Key

node -e "console.log('whatsapp_' + require('crypto').randomBytes(32).toString('hex'))"

Or use OpenSSL:

echo "whatsapp_$(openssl rand -hex 32)"

➕ Adding a New Command

To add a new command, edit the utils/commands.js file and add an entry to the COMMANDS object.

Command Structure

command_name: {
  type: 'simple' | 'script' | 'script_with_param',
  enabled: true, // enable or disable the command
  groupOnly: false, // true if only for groups
  allowedGroups: [], // array of allowed group IDs (or empty for all)
  pattern: '!commandname', // message prefix recognized as a command
  exact: true/false, // true: must match exactly, false: can have parameters after pattern
  reply: 'Reply text', // only for type: 'simple'
  script: 'script command', // only for type: 'script' or 'script_with_param'
  cwd: './scripts', // working directory for script (optional)
  successMessage: 'Message if success',
  errorMessage: 'Message if error',
  noDataMessage: 'Message if no data',
},

Example: Simple Command

hello: {
  type: 'simple',
  enabled: true,
  groupOnly: false,
  allowedGroups: [],
  pattern: '!hello',
  exact: true,
  reply: 'Hello there!',
},

Example: Script Command with Parameter

search: {
  type: 'script_with_param',
  script: 'node search_data.js',
  cwd: './scripts',
  enabled: true,
  groupOnly: true,
  allowedGroups: ['[email protected]'],
  pattern: '!search:', // message must start with !search:
  exact: false,
  successMessage: 'Search results sent to',
  errorMessage: 'Error executing search.',
  noDataMessage: 'No search results found.',
},

Tips:

• For commands with parameters, use exact: false and set the pattern as needed (!command or !command:)

🌐 API Documentation

All endpoints require the x-api-key header for authentication.

Response Format

All API responses follow a consistent JSON format:

Success Response:

{
  "status": "success",
  "message": "Operation completed successfully",
  "data": {
    // Response data here
  }
}

Error Response:

{
  "status": "error",
  "message": "Error description",
  "error": {
    "code": "ERROR_CODE",
    "details": "Additional error details"
  }
}

Content Type Support

The API supports two content types for flexible usage:

1. application/json - For text messages and file paths only
2. multipart/form-data - For file uploads with optional text and file paths

Health Check

Endpoint: GET /

Response:

{
  "status": "success",
  "message": "Server is running healthy",
  "data": {
    "status": "healthy",
    "uptime": "1h 0m 0s"
  }
}

Send Message

Endpoint: POST /send-message

Send Text Message (JSON)

curl -X POST http://localhost:3000/send-message \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "id": ["[email protected]"],
    "message": "Hello World!"
  }'

Send Text Message (Multiple Recipients)

curl -X POST http://localhost:3000/send-message \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "id": ["[email protected]", "[email protected]", "[email protected]"],
    "message": "Hello everyone!"
  }'

Send File from Path (JSON)

curl -X POST http://localhost:3000/send-message \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "id": ["[email protected]"],
    "message": "File from server",
    "filePaths": ["/home/user/documents/file.pdf", "/path/to/image.jpg"]
  }'

Send File Upload with Caption (Form-Data)

curl -X POST http://localhost:3000/send-message \
  -H "x-api-key: your_api_key" \
  -F "id[][email protected]" \
  -F "message=Check this file" \
  -F "files=@/path/to/your/file.jpg"

Send Mixed Files (Form-Data)

curl -X POST http://localhost:3000/send-message \
  -H "x-api-key: your_api_key" \
  -F "id[][email protected]" \
  -F "id[][email protected]" \
  -F "message=Multiple files example" \
  -F "files=@/local/upload/file1.jpg" \
  -F "filePaths[]=/server/path/file2.pdf" \
  -F "filePaths[]=/server/path/file3.docx"

Response:

{
  "status": "success",
  "message": "Sent to all recipients",
  "data": {
    "total": 2,
    "success": 2,
    "failed": 0
  }
}

Error Response (Partial Success):

{
  "status": "success",
  "message": "Sent to 1/2 recipients",
  "data": {
    "total": 2,
    "success": 1,
    "failed": 1,
    "errors": [
      {
        "id": "[email protected]",
        "error": "Chat not found"
      }
    ]
  }
}

Supported File Types (WhatsApp Compatible)

• Images: jpg, jpeg, png, gif, webp
• Videos: mp4, avi, mov, 3gp
• Audio: mp3, wav, ogg, aac, m4a
• Documents: pdf, doc, docx, xls, xlsx, ppt, pptx, txt

Get Group ID

Endpoint: GET /get-group-id?groupName=YourGroupName

Response:

{
  "status": "success",
  "message": "Group found successfully", 
  "data": {
    "groupName": "YourGroupName",
    "groupId": "[email protected]"
  }
}

🔧 API Parameters

Send Message Parameters

Parameter	Type	Required	Description	Content-Type
id	array	✅	Array of WhatsApp IDs	Both
message	string	✅	Text message content	Both
filePaths	array	❌	Array of server file paths	Both
files	file(s)	❌	Upload file(s) via form-data	multipart only

*At least one of: message, files, or filePaths is required.

Content Type Guidelines

• Use JSON (application/json) for:

  • Text-only messages
  • Server-side file paths
  • API integrations
  • Lightweight requests

• Use Form-Data (multipart/form-data) for:

  • File uploads from client
  • Mixed file sources (upload + paths)
  • Web form submissions

📚 Documentation

• WhatsApp Web JS Documentation
• Express.js Documentation

🤝 Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

📄 License

This project is licensed under the Apache-2.0 License. See the LICENSE file for details.

---

Built with ❤️ using modern JavaScript and clean architecture principles.