chrishubert/whatsapp-web-api repository overview

⁠WhatsApp Web.js REST API Wrapper

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 scalable, secure, and easy to integrate with other applications.

It came from my lack of knowlege with NodeJS and the need to create OTP authentication flow where I couldn't trust external services.

This project is far from perfect: 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.

⁠Table of Contents

1. Features⁠

2. Quick Start with Docker⁠

3. Run Locally⁠

4. Testing⁠

5. Documentation⁠

6. Contributing⁠

7. License⁠

8. Star History⁠

⁠Features

1. Available API endpoints

• API Initiate Session
• API Send Message
• API Validate if number is available on WhatsApp
• API Logout
• API Flush inactive sessions
• API HealthCheck

1. Available Callbacks (Webhook URL defined in .env file)

• Callback QR Code
• Callback new message
• Callback status change

1. Handle multiple client sessions (session data saved locally), identified by phone number

2. All Endpoints are secured by a global API key saved in the .env file

3. On server start, all previous clients are restored

⁠Quick Start with Docker

1. Clone the repository:

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

1. Edit the docker-compose.yml with updated ENV variables:

Prepare a valid callback URL (You can use https://webhook.site/⁠ to create a free webhook URL for testing)

- BASE_WEBHOOK_URL=https://example.com/webhook # UPDATE & MANDATORY

1. Run the Docker Compose:

docker-compose up -d

1. Request a QR code through API at http://localhost:3000/api/startSession/1

2. Use a QR generator service (https://www.nayuki.io/page/qr-code-generator-library⁠) with the qr received from the Callback

3. Scan the QR with your phone (it may take time to setup the session)

4. Enjoy!

⁠Run Locally

1. Clone the repository:

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

1. Install the dependencies:

npm install

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

cp env.example .env

1. Run the application in development mode:

npm run start

1. Access the API at http://localhost:3000

⁠Testing

Run the test suite with the following command:

npm test

⁠Documentation

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

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

⁠Star History