A custom WhatsApp API server built on Node.js, Express, and whatsapp-web.js. It provides a RESTful API to manage multiple, persistent WhatsApp sessions for messaging automation and system integration.
- Multi-Session Management: Run and manage several independent WhatsApp accounts simultaneously.
- Persistent Sessions: Sessions, connection status, and QR codes are persisted in a PostgreSQL database using TypeORM.
- RESTful API: Stateless endpoints for session lifecycle management and retrieving chats.
- QR Code Authentication: Dedicated endpoint to retrieve the QR code for authentication as JSON or an HTML image.
- Chat Retrieval: Get the list of all current chats for an active session.
- API Documentation: Fully documented REST API with Swagger UI available at
/docs. - TypeScript: Built with TypeScript and
tsyringe(DI container) for robust, type-safe code. - Structured Logging: Uses Pino for efficient and structured logging.
- Docker and Docker Compose (for easy database setup)
- Node.js (for running the server directly)
This setup runs the WAPIx server and the required PostgreSQL database.
-
Clone the repository:
git clone https://github.com/boriitoo/WAPIx cd wapix -
Start the database and build the server (PostgreSQL is required):
# This uses the docker-compose.yml file to start the PostgreSQL DB docker compose up -d db -
Install dependencies and build the TypeScript code:
npm install npm run build
-
Start the server:
npm start
The server will be running on port 3000.
Open your browser and navigate to http://localhost:3000/docs to explore the API.
Detailed API documentation is available via Swagger UI at /docs when the server is running. The documentation includes:
- Available endpoints
- Required parameters and data structures
- Status codes and descriptions
| Feature | Method | Path | Description |
|---|---|---|---|
| Create Session | POST |
/api/sessions |
Creates and starts a new WhatsApp session. |
| Get Session Details | GET |
/api/sessions/{name} |
Retrieves details for a specific session. |
| Get QR Code | GET |
/api/sessions/{name}/qr |
Returns the QR code for a new session (JSON or HTML). |
| Get Session Chats | GET |
/api/{name}/chats |
Retrieves the list of chats for a connected session. |
The application uses environment variables for configuration.
| Variable | Default Value | Description | Source |
|---|---|---|---|
PORT |
3000 |
The port the Express server listens on. | src/config/config.ts |
LOG_LEVEL |
debug (non-prod), info (prod) |
The minimum logging level for pino. | src/logger.ts |
| Database | See docker-compose.yml |
The PostgreSQL connection details (host: localhost, user/pass/db: test). |
src/data-source.ts, docker-compose.yml |
This project uses Prettier for code formatting and Husky to enforce formatting on commit.
npm run format