A robust, TypeScript-based, modular REST and WebSocket API for interacting with WhatsApp using the Baileys library.
This project uses @whiskeysockets/baileys, an unofficial third-party library. It is not affiliated with or supported by WhatsApp or Meta. Using this software uncautiously to interact with WhatsApp may violate their Terms of Service and could result in the permanent ban of your WhatsApp account. Use this API strictly at your own risk. The author assumes no liability or responsibility for any account bans, damages, or losses resulting from the use of this project.
Note: For legacy implementation details (pre-v1.0.0 architecture), please refer to the Legacy Documentation.
- Real-Time WebSockets: Instantly push connection statuses, logic hooks, and authentication QR codes directly to frontend clients over
socket.iorather than requiring polling. - REST API (v2): A highly modular MVC architectural layout for processing WhatsApp requests cleanly.
- Batch Messaging & Throttling: Features built-in smart queues that seamlessly handle string arrays for batch messaging with a baked-in 3-second anti-spam delay between requests.
- TypeScript Support: End-to-end typed for superior maintainability and safety around the Baileys library.
- Dynamic Version Spoofing: Connects seamlessly with the latest WhatsApp client version to combat
405 Method Not Allowedbugs natively.
Clone the repository:
git clone https://github.com/Azizham66/WhatsUP.git
cd WhatsUPInstall dependencies:
npm installLaunch Development Environment (Hot Reload):
npm run devBuild for Production:
npm run buildStart Built Server:
npm run startOne-Time WhatsApp Pairing (Print QR then exit):
npm run connectThis starts the API server, prints the QR code in your terminal, waits until WhatsApp is connected, then shuts the server down automatically (credentials remain saved in auth_info/).
By default, the REST API and the WebSocket server run on http://localhost:3000.
POST /api/v2/auth/connect- Triggers the WhatsApp connection and readies the WebSocket to emit the QR code.DELETE /api/v2/auth/logout- Terminates the active session and clears local credential caching.POST /connect&DELETE /logout- Exists for backwards compatibility.
POST /api/v2/message/send- Send a text or rich message to a user or group.- Also mapped to
POST /send-messagefor backwards compatibility.
- Also mapped to
Request Body Structure:
{
"jid": "1234567890@s.whatsapp.net",
"message": { "text": "Hello from API!" }
}Note: jid natively supports an array of strings (e.g. ["123@s...", "124@s..."]). The service will automatically sequentially send messages with anti-spam sleep throttling.
GET /api/v2/group- List comprehensive metadata for all participating groups.GET /api/v2/group/min- List condensed ID/Name properties of all groups.GET /api/v2/group/id/:id- Fetch comprehensive metadata for a specific group ID.GET /api/v2/group/id/:id/min- Fetch condensed data for a specific group ID.GET /api/v2/group/name/:name- Fetch metadata matching a string name.
All responses are packaged into a standard data wrapper:
{
"success": true,
"message": "Operation successful",
"data": { ... }
}Connect directly to the root namespace using socket.io-client:
import { io } from "socket.io-client";
const socket = io("http://localhost:3000");
// Subscribe to QR Code emissions to display to the user
socket.on("qr_code", (qrCodeString) => {
// Generates the raw QR string, convert with your favorite library!
});
// Follow Connection State
socket.on("status", (data) => {
// Returns elements like: { state: "connected" | "disconnected" }
});To see a fully functioning flow between the API and the WebSockets, refer to examples/test-login.js and run node examples/test-login.js.
Please see the CONTRIBUTING.md guide for rigid guidelines on our commit message formats, Single Responsibility requirements, and PR flows.
MIT
Abdulaziz Hamzah