WWebJS REST API

REST API wrapper for the 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. 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.

1. Quick Start with Docker

6. Deploy to Production

7. Contributing

8. License

9. Star History

Quick Start with Docker

Clone the repository:

bash
git clone https://github.com/avoylenko/wwebjs-api.git
cd wwebjs-api

Run the Docker Compose:

bash
docker compose pull && docker compose up

Visit http://localhost:3000/session/start/ABCD
Scan the QR on your console using WhatsApp mobile app -> Linked Device -> Link a Device (it may take time to setup the session)
Visit http://localhost:3000/client/getContacts/ABCD
EXTRA: Look at all the callbacks data in ./session/message_log.txt

Quick Start

Features

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	✅

Handle multiple client sessions (session data saved locally), identified by unique id
All endpoints may be secured by a global API key
On server start, all existing sessions are restored
Set messages automatically as read
Disable any of the callbacks

Run Locally

Clone the repository:

bash
git clone https://github.com/avoylenko/wwebjs-api.git
cd wwebjs-api

Install the dependencies:

bash
npm install

Note: To use the latest edge version of whatsapp-web.js directly from GitHub (with the latest features and fixes), modify the package.json dependency:

json
"whatsapp-web.js": "github:pedroslopez/whatsapp-web.js#main"

Then run npm install again. Be aware that edge versions may contain unstable features.

Copy the .env.example file to .env and update the required environment variables:

bash
cp .env.example .env

Run the application:

bash
npm run start

Access the API at http://localhost:3000

Testing

Run the test suite with the following command:

bash
npm run test

Documentation

API documentation can be found in the swagger.json file. See this file directly into Swagger Editor 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).

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 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.