Simple WhatsApp API

A lightweight REST API for sending and receiving WhatsApp messages using the Baileys library.

Introduction

This project is a simple WhatsApp API for personal and test automation projects. It connects to a single WhatsApp account via the WhatsApp or WhatsApp Business mobile app, and exposes local HTTP endpoints to send messages and receive incoming messages through webhooks.

Disclaimer This project is not production-ready (for example: no authentication, hardening, monitoring, abuse protection, or enterprise-grade safeguards). You must adapt the code to your own use case and security requirements before any serious deployment. It is not intended for commercial use, and is not affiliated with, endorsed by, or sponsored by WhatsApp or Meta. Any use of this project is entirely at your own risk.

Runtime Notes

• This project uses ESM ("type": "module") and TypeScript NodeNext module resolution.
• Built for Baileys v7.
• The API accepts recipient input as either phone numbers or WhatsApp JIDs.

Quick Start

1. Install dependencies:

npm install

2. Create a .env file:

cp .env.example .env

3. Run in development mode:

npm run dev

4. Build for production:

npm run build
npm start

Docker

This repository includes a Dockerfile and docker-compose.yml for easy deployment.

Run with Docker Compose (internal network)

docker compose up -d --build

• The API listens on port 3000 inside Docker.
• It is attached to the whatsapp_api_internal Docker network.
• No host port is published, so the service is intended for other containers on that network.

From another container on the same Docker network, call:

http://simple-whatsapp-api:3000

Persisted data

Compose mounts these folders so WhatsApp auth/session and webhook config survive container restarts:

• ./auth_info_baileys → /app/auth_info_baileys
• ./config_baileys → /app/config_baileys

API Endpoints

Health Check

• GET /health - Check API health status

Messages

• POST /api/messages/send - Send a WhatsApp message
• GET /api/messages/status/:messageId - Check message delivery status

Webhooks

• POST /api/webhooks/register - Register a webhook URL
• GET /api/webhooks - List all registered webhooks
• DELETE /api/webhooks/:id - Unregister a webhook

Connection

• GET /api/connection/status - Get WhatsApp connection status
• GET /api/connection/qr - Get QR code for authentication
• POST /api/connection/logout - Disconnect from WhatsApp

Example Requests

Send a Message

curl -X POST http://localhost:3000/api/messages/send \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155551234",
    "message": "Hello from WhatsApp API!"
  }'

Response:

{
  "success": true,
  "data": {
    "messageId": "3EB0123456789ABCDEF",
    "status": "sent"
  }
}

Note: Phone numbers should include country code. Accepted formats:

• +14155551234 (with + prefix)
• 14155551234 (without + prefix)
• 14155551234@s.whatsapp.net (PN JID format)
• <id>@lid (LID JID format)

For detailed documentation, see docs/SEND_MESSAGE.md

Register a Webhook

curl -X POST http://localhost:3000/api/webhooks/register \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-domain.com/webhook",
    "events": ["message"]
  }'

Currently supported webhook events: message

Response Format

All endpoints return responses in the following format:

{
  "success": true,
  "data": {},
  "error": "error message if applicable"
}

Development

• npm run dev - Run with hot-reload
• npm run build - Build TypeScript to JavaScript
• npm start - Run production build

License

ISC