Whisper API

Whisper API Docs

Whisper API Logo

Whisper API

A RESTful WhatsApp messaging API built with Express.js and Baileys library for seamless WhatsApp integration.

Node.js Express.js Baileys License CodeFactor

Features

Installation

  1. Clone the repository:
bash 
git clone https://github.com/ibnusyawall/whisper-api.git
cd whisper-api
  1. Install dependencies:
bash 
npm install
  1. Set up environment variables:
bash 
cp .env.example .env

  1. Configure your .env file with the required variables (see Environment Variables section below).

  2. Set up the database (MongoDB with Prisma):

bash 
# Generate Prisma client
npx prisma generate

# Push database schema to MongoDB
npx prisma db push
  1. Start the server:
bash 
# Development
npm run dev

# Production
npm start

API Endpoints

For comprehensive API documentation, including all available endpoints, request/response examples, and testing collections, please refer to:

📚 API Collections Documentation

The API supports multiple operational modes:

Key endpoint categories:

First Time Setup

Single Instance Mode Setup

  1. Ensure WHATSAPP_MODE=single or WHATSAPP_MODE=both in your .env file
  2. Start the server: npm start or npm run dev
  3. Scan the QR code displayed in the terminal using WhatsApp on your phone
  4. Check connection status: GET /api/v1/status
  5. Start sending messages using legacy endpoints

Multi-Instance Mode Setup

  1. Ensure WHATSAPP_MODE=multi or WHATSAPP_MODE=both in your .env file
  2. Configure DATABASE_URL in your .env file
  3. Set up the database: npx prisma generate && npx prisma db push
  4. Start the server: npm start or npm run dev
  5. Create a WhatsApp instance: POST /api/v1/instances
  6. Get the QR code: GET /api/v1/instances/{phone}/qr
  7. Scan the QR code with WhatsApp on your phone
  8. Check instance status: GET /api/v1/instances/{phone}/status
  9. Start sending messages using multi-instance endpoints

Quick Test Commands

bash 
# Check current mode
curl http://localhost:3000/api/v1/mode

# Create instance (multi-instance mode)
curl -X POST http://localhost:3000/api/v1/instances \
  -H "Content-Type: application/json" \
  -d '{"phone":"628123456789","name":"My Instance"}'

# Get QR code (multi-instance mode)
curl http://localhost:3000/api/v1/instances/628123456789/qr

Project Structure

src/
├── app.js                 # Main application file
├── config/                # Configuration files
│   └── mode.config.js     # WhatsApp mode configuration
├── controllers/           # Request handlers
│   ├── instance.controller.js # Multi-instance management
│   ├── log.controller.js     # Logging handler
│   ├── message.controller.js # Message sending handler
│   ├── mode.controller.js    # Mode information handler
│   ├── ping.controller.js    # Health check handler
│   ├── status.controller.js  # Status check handler
│   └── webhook.controller.js # Webhook management
├── core/                  # Core system components
│   └── plugin-manager.core.js # Plugin management system
├── database/              # Database connection and setup
│   └── prisma.js         # Prisma client configuration
├── plugins/              # Optional features as plugins
│   ├── admin-commands.plugin.js
│   ├── anti-mention.plugin.js
│   ├── eval-command.plugin.js
│   └── welcome-group.plugin.js
├── routes/               # API route definitions
│   └── index.js         # Main routing configuration
├── services/             # Business logic and services
│   ├── instanceLogService.js        # Instance logging service
│   ├── instanceService.js           # Instance management service
│   ├── messageService.js           # Message handling service
│   ├── webhookService.js           # Webhook management service
│   ├── whatsapp.service.js         # Legacy WhatsApp service
│   └── whatsappInstanceManager.service.js # Multi-instance manager
└── utils/                # Utility functions
    └── logger.js         # Winston logger utility

api-collections/          # API testing collections
├── global/              # Global endpoint tests
├── multi-instance/      # Multi-instance endpoint tests
├── single-instance/     # Legacy endpoint tests
├── postman_collection.json # Postman collection
└── README.md           # API documentation

auth/                    # Baileys authentication files
logs/                    # Application logs
prisma/                  # Prisma database schema
├── schema.prisma       # Database schema definition
tests/                   # Test files
├── database tests and setup

Environment Variables

Configure the following environment variables in your .env file:

Required Variables

bash 
# Server Configuration
PORT=3000                    # Port number for the server (default: 3000)
NODE_ENV=production          # Environment mode: development, production

# Database Configuration (Required for Multi-Instance Mode)
DATABASE_URL="mongodb://localhost:27017/whisper-api"
                            # MongoDB connection string for Prisma
                            # Format: mongodb://[username:password@]host[:port]/database
                            # Example: mongodb://user:pass@localhost:27017/whisper-api

# WhatsApp Configuration
WHATSAPP_MODE=multi         # Operational mode: single, multi, both
                            # - single: Legacy single-instance only
                            # - multi: Multi-instance management only (default)
                            # - both: Hybrid mode

# Logging Configuration
LOG_LEVEL=info              # Logging level: error, warn, info, debug
DEBUG=true                  # Enable verbose debug output: true, false

Environment Variable Details

Variable Description Default Required
PORT Server port number 3000 No
NODE_ENV Application environment production No
DATABASE_URL MongoDB connection string - Yes (for multi-instance)
WHATSAPP_MODE Operational mode multi No
LOG_LEVEL Logging verbosity info No
DEBUG Debug mode toggle false No

Mode Configuration

The WHATSAPP_MODE variable determines which endpoints are available:

Database Setup

For multi-instance functionality, a MongoDB database with replica set support is required. This is essential for Prisma to handle transactions and ensure data consistency. You can either use a cloud provider that supports replica sets or set one up locally using Docker.

Important Note: Standard single-node MongoDB instances (like the default mongo:latest Docker image) will not work for multi-instance mode due to the lack of replica set functionality.

MongoDB Atlas provides free-tier clusters with replica sets enabled by default. This is the easiest and most reliable way to get started.

  1. Create a free cluster on MongoDB Atlas.
  2. Get your connection string (e.g., mongodb+srv://user:[email protected]/whisper-api).
  3. Update DATABASE_URL in your .env file.

Option 2: Local Docker with Replica Set

You can run a local MongoDB replica set using the provided Docker Compose file. This is ideal for development and testing.

  1. Ensure you have Docker and Docker Compose installed.

  2. Run the following command to start a single-node replica set:

    bash 
    docker-compose up -d

  3. Update your DATABASE_URL to use the local replica set:

    bash 
    DATABASE_URL="mongodb://localhost:27017/whisper-api?replicaSet=rs0&directConnection=true"

  4. Stop the replica set when you're done:

    bash 
    docker-compose down

This setup provides a complete, isolated environment for running the database with the required replica set configuration.

Phone Number Format

Group ID Format

Logging

Error Handling

The API returns standardized error responses:

json 
{
  "success": false,
  "error": "Error type",
  "message": "Detailed error message",
  "timestamp": "2025-07-13T10:00:00.000Z"
}

Deployment

Railway

bash 
# Install Railway CLI
npm install -g @railway/cli

# Deploy
railway login
railway init
railway up

Vercel

bash 
# Install Vercel CLI
npm install -g vercel

# Deploy
vercel --prod

Render

  1. Connect your GitHub repository
  2. Set build command: npm install
  3. Set start command: npm start
  4. Deploy

VPS/Traditional Hosting

bash 
# Using PM2 for process management
npm install -g pm2
pm2 start src/app.js --name whisper-api
pm2 startup
pm2 save

Usage Examples

Using cURL

bash 
# Health check
curl -X GET http://localhost:3000/api/v1/ping

# Send message
curl -X POST http://localhost:3000/api/v1/message \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber":"628123456789","message":"Hello World!"}'

# Check status
curl -X GET http://localhost:3000/api/v1/status

Using JavaScript/Node.js

javascript 
const axios = require('axios');

// Send message
const sendMessage = async () => {
  try {
    const response = await axios.post('http://localhost:3000/api/v1/message', {
      phoneNumber: '628123456789',
      message: 'Hello from Whisper API!'
    });
    console.log(response.data);
  } catch (error) {
    console.error(error.response.data);
  }
};

Notes

General Notes

Single Instance Mode

Multi-Instance Mode

Webhooks

Database

Common Issues

1. QR Code Issues

Single Instance Mode

Multi-Instance Mode

2. Connection and Message Issues

Single Instance Mode

Multi-Instance Mode

3. Database Issues (Multi-Instance Mode)

4. Server and Configuration Issues

5. Performance Issues

6. Development and Testing Issues

Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Disclaimer

This project is for educational and development purposes. Please ensure you comply with WhatsApp's Terms of Service when using this API.

Support

If you found this project helpful, please give it a ⭐ star!

For issues and questions, please create an issue in the GitHub repository.