WhatsApp 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 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:

git clone https://github.com/chrishubert/whatsapp-api.git
cd whatsapp-api

Run the Docker Compose:

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

Features

API and Callbacks

Actions	Status	Sessions	Status	Callbacks	Status
Send Image Message	✅	Initiate session	✅	Callback QR code	✅
Send Video Message	✅	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	✅	Healthcheck	✅
Send Button Message	✅	Local test callback
Send Contact Message	✅
Send List Message	✅
Set Status	✅
Send Button With Media	✅
Is On Whatsapp?	✅
Download Profile Pic	✅
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:

git clone https://github.com/chrishubert/whatsapp-api.git
cd whatsapp-api

Install the dependencies:

npm install

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

cp .env.example .env

Run the application:

npm run start

Access the API at http://localhost:3000

Testing

Run the test suite with the following command:

npm run test

Documentation

API documentation can be found in the swagger.yml file. See this file directly into Swagger Editor or any other OpenAPI-compatible tool to view and interact with the API documentation.

This documention 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

Deploy to Production

Load the docker image in docker-compose, or your Kubernetes environment
Disable the ENABLE_LOCAL_CALLBACK_EXAMPLE environment variable
Run periodically the api/terminateInactiveSessions endpoint to prevent useless sessions to take up space and ressources

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.

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

ubay887/whatsapp-api