Caution

Whatsback Web and whatsapp-web.js are not officially supported by WhatsApp. Use this project at your own risk.

Whatsback Provider is a simple WhatsApp provider that offers basic functionality such as predefined static commands, sending messages to contacts or groups, and listing all contacts. This project leverages the unofficial whatsapp-web.js package to interface with WhatsApp Web.

Important

It is not guaranteed you will not be blocked by using this method. WhatsApp does not allow bots or unofficial clients on their platform, so this shouldn't be considered totally safe.

Features

• Predefined Static Commands: Quickly execute common commands without the need for manual input.
• Send Message to Contact: Programmatically send message directly to individual contacts.
• Send Message to Group: Programmatically send message to the groups.
• List All Contacts: Retrieve and display a list of all contacts available on the WhatsApp account.
• Schedule Message: Schedule a message to be sent at a later time.

---

Leave Your Reviews & Start ⭐ This Repository

---

Table of Contents

• ⚠️ Caution
• ✨ Features
• 🚀 Getting Started
  • Prerequisites
  • Key Configuration Options
• 🐳 Docker Installation
  • Docker CLI
  • docker-compose.yml
• 💻 Source Installation
• 🏃 Running the Project
• 🔌 Available REST API
• 🔒 Security Considerations
• 🤝 Contributing
• 💖 Donate or Sponsoring
• 📢 Disclaimer
• 📄 License

Getting Started

Prerequisites

• Node.js (v20 or later recommended)
• npm (comes with Node.js)
• A valid WhatsApp account

Key Configuration Options

Environment Variable	Description	Default
NODE_ENV	Runtime environment	production
APP_PORT	Application port	5001
UI_PORT	External exposed port	8169
DB_PATH	Path to SQLite database	/data/database.sqlite
TZ	Set your default timezone	Asia/Jakarta default UTC

Docker Installation

Docker CLI

1. Pull the image:

   docker pull ghcr.io/darkterminal/whatsback-web:latest

2. Create Network

docker network create whatsback-net

3. Create Volume

docker volume create whatsback-db

4. Run Whatsback Application Container

docker run -d \
  --name whatsback-app-provider \
  --network whatsback-net \
  -p 8169:5001 \
  -e NODE_ENV=production \
  -e APP_PORT=5001 \
  -e DB_PATH=/data/database.sqlite \
  -v whatsback-db:/data \
  ghcr.io/darkterminal/whatsback-web:latest

5. Run Whatsback Cronjob Container

docker run -d \
  --name whatsback-app-cronjob \
  --network whatsback-net \
  -e NODE_ENV=production \
  -e APP_HOST=whatsback-app-provider \
  -e DB_PATH=/data/database.sqlite \
  -v whatsback-db:/data \
  ghcr.io/darkterminal/whatsback-web:latest \
  sh -c "./wait-for whatsback-app-provider:5001 -t 120 -- node cronjob.js"

docker-compose.yml

services:
  app:
    image: ghcr.io/darkterminal/whatsback-web:latest
    container_name: whatsback-app-provider
    ports:
      - "${UI_PORT:-8169}:5001"
    environment:
      - NODE_ENV=production
      - APP_PORT=${APP_PORT:-5001}
      - DB_PATH=/data/database.sqlite
    volumes:
      - db-data:/data
    networks:
      - app_net
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:$$APP_PORT/health || exit 1"]
      interval: 15s
      timeout: 10s
      retries: 5

  cronjob:
    image: ghcr.io/darkterminal/whatsback-web:latest
    container_name: whatsback-app-cronjob
    environment:
      - NODE_ENV=production
      - APP_HOST=app
      - DB_PATH=/data/database.sqlite
    volumes:
      - db-data:/data
    command: sh -c "./wait-for app:5001 -t 120 -- node cronjob.js"
    networks:
      - app_net
    depends_on:
      app:
        condition: service_healthy

networks:
  app_net:
    driver: bridge

volumes:
  db-data:

Source Installation

git clone https://github.com/darkterminal/whatsback-web.git
cd whatsback-web
npm install

Running the Project

For development, start the server with:

npm run dev

For production, start the server with:

NODE_ENV=production node server.js

Your server should start on the port defined in the .env file (default is 5001).

Available REST API

You can read the REST API documentation here

Security Considerations

• This project uses middleware like Helmet, express-rate-limit, and hpp to help protect against common web vulnerabilities.
• Be aware that using an unofficial API (whatsapp-web.js) can carry risks with regard to WhatsApp's terms of service.
• Whatsback Web and whatsapp-web.js are not officially supported by WhatsApp. Use this project at your own risk.
• It is not guaranteed you will not be blocked by using this method. WhatsApp does not allow bots or unofficial clients on their platform, so this shouldn't be considered totally safe.

Contributing

Contributions are welcome! Please open issues or pull requests to improve the project.

Donate or Sponsoring

You can support the maintainer of this project through the button and links below:

• Support via GitHub Sponsors
• Support via Saweria

Disclaimer

This project is not affiliated, associated, authorized, endorsed by, or in any way officially connected with WhatsApp or any of its subsidiaries or its affiliates. The official WhatsApp website can be found at whatsapp.com. "WhatsApp" as well as related names, marks, emblems and images are registered trademarks of their respective owners. Also it is not guaranteed you will not be blocked by using this method. WhatsApp does not allow bots or unofficial clients on their platform, so this shouldn't be considered totally safe.

License

Copyright 2025 Imam Ali Mustofa

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.