DISCLAIMER: this not a fork or project takeover. This is just an implementation of an already available PR wich didn't got merged! # WWebJS REST API REST API wrapper for the [whatsapp-web.js](https://github.com/pedroslopez/whatsapp-web.js) library, providing an easy-to-use interface to interact with the WhatsApp Web platform. It is designed to be used as a docker container, scalable, secure, and easy to integrate with other non-NodeJS projects. This project is a fork of [whatsapp-api](https://github.com/chrishubert/whatsapp-api). As the project was abandoned by the original author, all future improvements will be in this repo. The project is a work in progress: star it, create issues, features or pull requests ❣️ **NOTE**: I can't guarantee you will not be blocked by using this method, although it has worked for me. WhatsApp does not allow bots or unofficial clients on their platform, so this shouldn't be considered totally safe. ## Patched public distribution This Forgejo fork bundles a patched `whatsapp-web.js` release that tolerates WhatsApp Web message IDs exposed as `$1` instead of `_serialized`. - Source repository: [eddy/wwebjs-api](https://git.eddydevink.nl/eddy/wwebjs-api) - Patched library: [eddy/whatsapp-web.js](https://git.eddydevink.nl/eddy/whatsapp-web.js) - Public image: `git.eddydevink.nl/eddy/wwebjs-api:1.34.7-serialized-id-2dd7653` The image is built from the Dockerfile in this repository and pins the patched library archive through `package-lock.json`. It is not an official WhatsApp or whatsapp-web.js release. ## Quick Start with the patched image ```bash git clone https://git.eddydevink.nl/eddy/wwebjs-api.git cd wwebjs-api cp .env.example .env # Set BASE_WEBHOOK_URL and a strong API_KEY in .env. docker compose pull docker compose up -d ``` The default Compose file uses the public patched image. The API listens on `PORT` (3000 by default). Start a session and scan its QR code with: ```bash curl http://localhost:3000/session/start/ABCD ``` For a completely local, reproducible build instead of pulling the image: ```bash docker compose -f docker-compose.build.yml up -d --build ``` The build uses the committed `vendor/whatsapp-web.js-1.34.7.tgz` archive and does not download an unpatched upstream `main` branch. ## Table of Contents [1. Quick Start with the patched image](#quick-start-with-the-patched-image) [2. Features](#features) [3. Run Locally](#run-locally) [4. Testing](#testing) [5. Documentation](#documentation) [6. Deploy to Production](#deploy-to-production) [7. Contributing](#contributing) [8. License](#license) [9. Star History](#star-history) ## Features 1. API and Callbacks | Actions | Status | Sessions | Status | Callbacks | Status | | ----------------------------| ------| ----------------------------------------| ------| ----------------------------------------------| ------| | Send Image Message | ✅ | Initiate session | ✅ | Callback QR code | ✅ | | Send Video Message(requires Google Chrome) | ✅ | Terminate session | ✅ | Callback new message | ✅ | | Send Audio Message | ✅ | Terminate inactive sessions | ✅ | Callback status change | ✅ | | Send Document Message | ✅ | Terminate all sessions | ✅ | Callback message media attachment | ✅ | | Send File URL | ✅ | Restart session | ✅ | | | | Send Contact Message | ✅ | Get session status | ✅ | | | | Send Poll Message | ✅ | Health Check | ✅ | | | | Edit Message | ✅ | | | | | | Set Status | ✅ | | | | | | Is On Whatsapp? | ✅ | | | | | | Download Profile Picture | ✅ | | | | | | User Status | ✅ | | | | | | Block/Unblock User | ✅ | | | | | | Update Profile Picture | ✅ | | | | | | Create Group | ✅ | | | | | | Leave Group | ✅ | | | | | | All Groups | ✅ | | | | | | Invite User | ✅ | | | | | | Make Admin | ✅ | | | | | | Demote Admin | ✅ | | | | | | Group Invite Code | ✅ | | | | | | Update Group Participants | ✅ | | | | | | Update Group Setting | ✅ | | | | | | Update Group Subject | ✅ | | | | | | Update Group Description | ✅ | | | | | 1. Handle multiple client sessions (session data saved locally), identified by unique id 2. All endpoints may be secured by a global API key 3. On server start, all existing sessions are restored 4. Set messages automatically as read 5. Disable any of the callbacks ## Run Locally Clone the public Forgejo repository: ```bash git clone https://git.eddydevink.nl/eddy/wwebjs-api.git cd wwebjs-api ``` Install dependencies for local Node.js development: ```bash npm ci ``` The dependency is pinned to the patched `whatsapp-web.js` archive in `vendor/`. Do not replace it with upstream `main` when testing this fix. For the recommended container workflow, use the public image or the reproducible local build described above. Copy the environment template and configure the required values: ```bash cp .env.example .env ``` Run the application: ```bash npm run start ``` The API is available at `http://localhost:3000` by default. ## Testing Run the test suite with the following command: ```bash npm run test ``` ## Documentation API documentation can be found in the [`swagger.json`](https://raw.githubusercontent.com/avoylenko/wwebjs-api/main/swagger.json) file. See this file directly into [Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/avoylenko/wwebjs-api/main/swagger.json) or any other OpenAPI-compatible tool to view and interact with the API documentation. This documentation is straightforward if you are familiar with whatsapp-web.js library (https://docs.wwebjs.dev/) If you are still confused - open an issue and I'll improve it. Also, there is an option to run the documentation endpoint locally by setting the `ENABLE_SWAGGER_ENDPOINT` environment variable. Restart the service and go to `/api-docs` endpoint to see it. By default, all callback events are delivered to the webhook defined with the `BASE_WEBHOOK_URL` environment variable. This can be overridden by setting the `*_WEBHOOK_URL` environment variable, where `*` is your sessionId. For example, if you have the sessionId defined as `DEMO`, the environment variable must be `DEMO_WEBHOOK_URL`. By setting the `DISABLED_CALLBACKS` environment variable you can specify what events you are **not** willing to receive on your webhook. By setting the `ENABLE_WEBHOOK` environment to `FALSE` you can disable webhook dispatching. This will help you if you want to switch to websocket method(see below). ### Web dashboard The service ships with a simple web UI for session management. It is disabled by default — set the `ENABLE_WEB_UI` environment variable to `TRUE`, restart the service and go to the `/dashboard` endpoint. The dashboard lets you start, stop, restart and terminate sessions, scan the pairing QR code (or request a pairing code for a phone number) and inspect connected session details. If the `API_KEY` environment variable is set, enter the key in the dashboard header — it is stored in your browser's localStorage and sent as the `x-api-key` header with every request. ### Scanning QR code In order to validate a new WhatsApp Web instance you need to scan the QR code using your mobile phone. Official documentation can be found at (https://faq.whatsapp.com/1079327266110265/?cms_platform=android) page. The service itself delivers the QR code content as a webhook event or you can use the REST endpoints (`/session/qr/:sessionId` or `/session/qr/:sessionId/image` to get the QR code as a png image). ### Outbound Proxy The Chromium instance that powers each session can be routed through an outbound proxy by setting the `PROXY_URL` environment variable (e.g. `http://10.0.0.10:8118`, `https://...`, or `socks5://...`). When `PROXY_URL` is empty, sessions connect directly with no behavior change. If the proxy requires authentication, set `PROXY_USERNAME` and `PROXY_PASSWORD`. When both are defined they are forwarded to Chromium as HTTP Basic auth via puppeteer's `proxyAuthentication`. For API-key vendor proxies, use the vendor-specified username (often `api-key`) and the key itself as the password. ### WebSocket mode The service can dispatch realtime events through websocket connection. By default, the websocket is not activated, so you need manually set the `ENABLE_WEBSOCKET` environment variable to activate it. The server activates a new websocket instance per each active session. The websocket path is `/ws/:sessionId`, where sessionId is your configured session name. The websocket supports ping/pong scheme to keep the socket running. The below example shows how to receive the events for **test** session. ``` const ws = new WebSocket('ws://127.0.0.1:3000/ws/test'); ws.on('message', (data) => { // consume the events }); ``` ## Deploy to Production - Load the docker image in docker-compose, or your Kubernetes environment - Disable the `ENABLE_LOCAL_CALLBACK_EXAMPLE` environment variable - Set the `API_KEY` environment variable to protect the REST endpoints - Run periodically the `/api/terminateInactiveSessions` endpoint to prevent useless sessions to take up space and resources(only in case you are not in control of the sessions) ## Contributing Please read [CONTRIBUTING.md](./CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us. ## 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 https://whatsapp.com. "WhatsApp" as well as related names, marks, emblems and images are registered trademarks of their respective owners. ## License This project is licensed under the MIT License - see the [LICENSE.md](./LICENSE.md) file for details. ## Star History [![Star History Chart](https://api.star-history.com/svg?repos=avoylenko/wwebjs-api&type=Date)](https://star-history.com/#avoylenko/wwebjs-api&Date)