baileys-rest

Lightweight MIT REST API for WhatsApp via Baileys. The free Evolution API alternative.

Why This Exists

Evolution API has 8k+ stars but is GPL-3 licensed, heavy, opinionated, and runs as a full app/Docker stack. Many developers want a lightweight MIT alternative they can npm install and embed into their own Node.js application, or run as a standalone server.

baileys-rest fills this gap:

• MIT licensed - Use commercially without restrictions
• Lightweight - Single dependency on @whiskeysockets/baileys
• Flexible - Run standalone or embed in your app
• Composable - Integrates seamlessly with baileys-antiban and baileys-webhooks

Installation

npm install baileys-rest @whiskeysockets/baileys

Quick Start

Standalone Server (CLI)

npx baileys-rest --port 3000 --auth-dir ./auth --api-key supersecret

This starts an Express server on port 3000. On first run, scan the QR code or use pairing code to authenticate.

Embedded Mode

import { createBaileysRest } from 'baileys-rest';

const server = await createBaileysRest({
  authDir: './auth',
  apiKey: process.env.WA_API_KEY!,
  withAntiban: true,         // Optional: wraps socket via baileys-antiban
  antibanPreset: 'moderate',
  port: 3000
});

await server.listen();

API Reference

All endpoints require X-API-Key header matching your configured API key.

Auth & Status

| Endpoint | Method | Description | Auth Required | |----------|--------|-------------|---------------| | /health | GET | Server health and connection status | No | | /auth/qr | GET | Get QR code for pairing (returns 204 if already connected) | Yes | | /auth/status | GET | Check connection status and JID | Yes | | /auth/pair | POST | Generate pairing code for phone number | Yes | | /auth/logout | POST | Logout and clear session | Yes |

Messages

| Endpoint | Method | Description | |----------|--------|-------------| | /messages/text | POST | Send text message | | /messages/image | POST | Send image with optional caption | | /messages/document | POST | Send document | | /messages/:jid | GET | Get recent messages (cached, last 100 per JID) |

Groups

| Endpoint | Method | Description | |----------|--------|-------------| | /groups | GET | List all groups | | /groups/:id | GET | Get group metadata | | /groups/:id/messages | POST | Send message to group |

Webhooks

| Endpoint | Method | Description | |----------|--------|-------------| | /webhooks | POST | Register webhook | | /webhooks | GET | List webhooks | | /webhooks/:id | DELETE | Remove webhook |

Examples

Send Text Message

curl -X POST http://localhost:3000/messages/text \
  -H "X-API-Key: supersecret" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "27821234567",
    "text": "Hello from baileys-rest!"
  }'

Send Image

curl -X POST http://localhost:3000/messages/image \
  -H "X-API-Key: supersecret" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "27821234567",
    "imageUrl": "https://example.com/image.jpg",
    "caption": "Check this out!"
  }'

Get Pairing Code

curl -X POST http://localhost:3000/auth/pair \
  -H "X-API-Key: supersecret" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber": "27821234567"}'

Composability

With baileys-antiban

Add rate limiting, warmup, and health monitoring:

import { createBaileysRest } from 'baileys-rest';

const server = await createBaileysRest({
  authDir: './auth',
  apiKey: 'supersecret',
  withAntiban: true,         // Automatically wraps socket
  antibanPreset: 'moderate'
});

First install: npm install baileys-antiban

With baileys-webhooks

Coming in v0.2 - full webhook event delivery system.

CLI Options

baileys-rest [options]

Options:
  --port <number>          Port to listen on (default: 3000)
  --auth-dir <path>        Directory for auth session (default: ./auth)
  --api-key <key>          API key for authentication (required)
  --with-antiban           Enable baileys-antiban if installed
  --antiban-preset <p>     Preset: conservative|moderate|aggressive (default: moderate)
  --cors-origin <origin>   CORS origin (default: *)
  --help                   Show this help message
  --version                Show version

Deployment

Docker Compose

version: '3.8'

services:
  baileys-rest:
    image: node:20-alpine
    working_dir: /app
    command: npx baileys-rest --port 3000 --auth-dir /data --api-key ${WA_API_KEY}
    ports:
      - "3000:3000"
    volumes:
      - ./auth:/data
    environment:
      - WA_API_KEY=${WA_API_KEY}
    restart: unless-stopped

Roadmap (v0.2)

• Media upload from disk/URL/base64
• Story/status posting
• Contact info retrieval
• Presence broadcast
• Full webhook event delivery system via baileys-webhooks
• Message editing/deletion
• Reaction support
• Poll creation

License

MIT - See LICENSE file for details.

Author

Kobus Wentzel [email protected]

Related Projects

• baileys-antiban - Anti-ban middleware with rate limiting and warmup
• @whiskeysockets/baileys - The underlying WhatsApp Web library

Contributing

Contributions welcome! Please open an issue or PR on GitHub.

Support

• GitHub Issues: https://github.com/kobie3717/baileys-rest/issues
• NPM: https://www.npmjs.com/package/baileys-rest