https://github.com/darkterminal/whatsback-web
Host Your Own WhatsApp Provider - Free and Open Source
https://github.com/darkterminal/whatsback-web
api docker docker-image expressjs javascript nodejs tailwindcss webapp whatsapp whatsapp-api whatsapp-web
Last synced: 23 days ago
JSON representation
Host Your Own WhatsApp Provider - Free and Open Source
- Host: GitHub
- URL: https://github.com/darkterminal/whatsback-web
- Owner: darkterminal
- License: apache-2.0
- Created: 2025-02-14T14:48:39.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2025-04-11T12:56:30.000Z (about 1 month ago)
- Last Synced: 2025-04-23T01:53:39.804Z (23 days ago)
- Topics: api, docker, docker-image, expressjs, javascript, nodejs, tailwindcss, webapp, whatsapp, whatsapp-api, whatsapp-web
- Language: JavaScript
- Homepage: https://dev.to/darkterminal/whatsback-web-automate-whatsapp-with-power-responsibility-ap6
- Size: 1.25 MB
- Stars: 13
- Watchers: 1
- Forks: 4
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
> [!CAUTION]
> **Whatsback Web** and [whatsapp-web.js](https://github.com/pedroslopez/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](https://github.com/pedroslopez/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](#caution)
- [✨ Features](#features)
- [🚀 Getting Started](#getting-started)
- [Prerequisites](#prerequisites)
- [Key Configuration Options](#key-configuration-options)
- [🐳 Docker Installation](#docker-installation)
- [Docker CLI](#docker-cli)
- [docker-compose.yml](#docker-composeyml)
- [💻 Source Installation](#source-installation)
- [🏃 Running the Project](#running-the-project)
- [🔌 Available REST API](#available-rest-api)
- [🔒 Security Considerations](#security-considerations)
- [🤝 Contributing](#contributing)
- [💖 Donate or Sponsoring](#donate-or-sponsoring)
- [📢 Disclaimer](#disclaimer)
- [📄 License](#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:**
```bash
docker pull ghcr.io/darkterminal/whatsback-web:latest
```
2. **Create Network**
```bash
docker network create whatsback-net
```
3. **Create Volume**
```bash
docker volume create whatsback-db
```
4. **Run Whatsback Application Container**
```bash
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**
```bash
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
```yaml
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
```bash
git clone https://github.com/darkterminal/whatsback-web.git
cd whatsback-web
npm install
```
### Running the Project
For development, start the server with:
```bash
npm run dev
```
For production, start the server with:
```bash
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](WHATSBACK-API.md)
## 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](https://github.com/sponsors/darkterminal)
- [Support via Saweria](https://saweria.co/darkterminal)
## 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](https://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.
```
## GitAds Sponsored
[](https://gitads.dev/v1/ad-track?source=tursodatabase/turso-driver-laravel@github)