{"id":29479208,"url":"https://github.com/ibnusyawall/whisper-api","last_synced_at":"2025-10-25T09:32:06.839Z","repository":{"id":304544338,"uuid":"1018679305","full_name":"ibnusyawall/whisper-api","owner":"ibnusyawall","description":"RESTful WhatsApp messaging API with Express.js and Baileys library","archived":false,"fork":false,"pushed_at":"2025-07-13T19:07:22.000Z","size":19,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-13T20:39:02.377Z","etag":null,"topics":["api-gateway","automation","baileys","express","messaging-api","nodejs","rest-api","webhook","whatsapp-api","whatsapp-bot"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ibnusyawall.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-12T19:40:19.000Z","updated_at":"2025-07-13T19:07:25.000Z","dependencies_parsed_at":"2025-07-13T20:39:06.493Z","dependency_job_id":"fe24f0bb-d24a-43a3-9033-d7511261e271","html_url":"https://github.com/ibnusyawall/whisper-api","commit_stats":null,"previous_names":["ibnusyawall/whisper-api"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ibnusyawall/whisper-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibnusyawall%2Fwhisper-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibnusyawall%2Fwhisper-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibnusyawall%2Fwhisper-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibnusyawall%2Fwhisper-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ibnusyawall","download_url":"https://codeload.github.com/ibnusyawall/whisper-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibnusyawall%2Fwhisper-api/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265344201,"owners_count":23750553,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-gateway","automation","baileys","express","messaging-api","nodejs","rest-api","webhook","whatsapp-api","whatsapp-bot"],"created_at":"2025-07-14T20:12:43.303Z","updated_at":"2025-10-25T09:32:06.833Z","avatar_url":"https://github.com/ibnusyawall.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"logo.svg\" alt=\"Whisper API Logo\" width=\"120\" height=\"120\"\u003e\n  \n  # Whisper API\n  \n  **A RESTful WhatsApp messaging API built with Express.js and Baileys library for seamless WhatsApp integration.**\n  \n  [![Node.js](https://img.shields.io/badge/Node.js-v20+-green)](https://nodejs.org/en)\n  [![Express.js](https://img.shields.io/badge/Express.js-v5.1+-blue)](https://expressjs.com/)\n  [![Baileys](https://img.shields.io/badge/Baileys-v6.7+-purple)](https://github.com/WhiskeySockets/Baileys/)\n  [![License](https://img.shields.io/badge/License-MIT-yellow)](https://github.com/ibnusyawall/whisper-api/blob/main/LICENSE)\n  [![CodeFactor](https://www.codefactor.io/repository/github/ibnusyawall/whisper-api/badge)](https://www.codefactor.io/repository/github/ibnusyawall/whisper-api)\n\u003c/div\u003e\n\n## Features\n\n- 🏓 **Ping/Pong** - Health check endpoint\n- 📊 **Status Check** - WhatsApp connection status monitoring\n- 📨 **Send Message** - Send text messages to personal chats\n- 👥 **Send Group Message** - Send messages to WhatsApp groups\n- 🔗 **Webhooks** - Real-time event notifications via HTTP webhooks\n- 🏢 **Multi-Instance** - Manage multiple WhatsApp instances simultaneously\n- 🔌 **Plugin Management** - Per-instance plugin configuration and control\n- 📋 **Logging** - Comprehensive logging for all activities\n- 🔧 **Modular Structure** - Clean, maintainable, and scalable code structure\n\n## Installation\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/ibnusyawall/whisper-api.git\ncd whisper-api\n```\n\n2. Install dependencies:\n```bash\nnpm install\n```\n\n3. Set up environment variables:\n```bash\ncp .env.example .env\n```\n\n4. Configure your `.env` file with the required variables (see Environment Variables section below).\n\n5. Set up the database (MongoDB with Prisma):\n```bash\n# Generate Prisma client\nnpx prisma generate\n\n# Push database schema to MongoDB\nnpx prisma db push\n```\n\n6. Start the server:\n```bash\n# Development\nnpm run dev\n\n# Production\nnpm start\n```\n\n## API Endpoints\n\nFor comprehensive API documentation, including all available endpoints, request/response examples, and testing collections, please refer to:\n\n📚 **[API Collections Documentation](api-collections/README.md)**\n\nThe API supports multiple operational modes:\n- **Single Instance Mode**: Legacy endpoints for single WhatsApp instance\n- **Multi-Instance Mode**: Advanced endpoints for managing multiple WhatsApp instances\n- **Hybrid Mode**: Both single and multi-instance endpoints available simultaneously\n\nKey endpoint categories:\n- 🌐 **Global Endpoints**: Mode information and system status\n- 🔀 **Single Instance (Legacy)**: Basic WhatsApp messaging functionality\n- 🏢 **Multi-Instance Management**: Instance creation, monitoring, messaging, webhook management, and plugin configuration\n\n## First Time Setup\n\n### Single Instance Mode Setup\n1. Ensure `WHATSAPP_MODE=single` or `WHATSAPP_MODE=both` in your `.env` file\n2. Start the server: `npm start` or `npm run dev`\n3. Scan the QR code displayed in the terminal using WhatsApp on your phone\n4. Check connection status: `GET /api/v1/status`\n5. Start sending messages using legacy endpoints\n\n### Multi-Instance Mode Setup\n1. Ensure `WHATSAPP_MODE=multi` or `WHATSAPP_MODE=both` in your `.env` file\n2. Configure `DATABASE_URL` in your `.env` file\n3. Set up the database: `npx prisma generate \u0026\u0026 npx prisma db push`\n4. Start the server: `npm start` or `npm run dev`\n5. Create a WhatsApp instance: `POST /api/v1/instances`\n6. Get the QR code: `GET /api/v1/instances/{phone}/qr`\n7. Scan the QR code with WhatsApp on your phone\n8. Check instance status: `GET /api/v1/instances/{phone}/status`\n9. Start sending messages using multi-instance endpoints\n\n### Quick Test Commands\n```bash\n# Check current mode\ncurl http://localhost:3000/api/v1/mode\n\n# Create instance (multi-instance mode)\ncurl -X POST http://localhost:3000/api/v1/instances \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"phone\":\"628123456789\",\"name\":\"My Instance\"}'\n\n# Get QR code (multi-instance mode)\ncurl http://localhost:3000/api/v1/instances/628123456789/qr\n```\n\n## Project Structure\n\n```\nsrc/\n├── app.js                 # Main application file\n├── config/                # Configuration files\n│   └── mode.config.js     # WhatsApp mode configuration\n├── controllers/           # Request handlers\n│   ├── instance.controller.js # Multi-instance management\n│   ├── log.controller.js     # Logging handler\n│   ├── message.controller.js # Message sending handler\n│   ├── mode.controller.js    # Mode information handler\n│   ├── ping.controller.js    # Health check handler\n│   ├── status.controller.js  # Status check handler\n│   └── webhook.controller.js # Webhook management\n├── core/                  # Core system components\n│   └── plugin-manager.core.js # Plugin management system\n├── database/              # Database connection and setup\n│   └── prisma.js         # Prisma client configuration\n├── plugins/              # Optional features as plugins\n│   ├── admin-commands.plugin.js\n│   ├── anti-mention.plugin.js\n│   ├── eval-command.plugin.js\n│   └── welcome-group.plugin.js\n├── routes/               # API route definitions\n│   └── index.js         # Main routing configuration\n├── services/             # Business logic and services\n│   ├── instanceLogService.js        # Instance logging service\n│   ├── instanceService.js           # Instance management service\n│   ├── messageService.js           # Message handling service\n│   ├── webhookService.js           # Webhook management service\n│   ├── whatsapp.service.js         # Legacy WhatsApp service\n│   └── whatsappInstanceManager.service.js # Multi-instance manager\n└── utils/                # Utility functions\n    └── logger.js         # Winston logger utility\n\napi-collections/          # API testing collections\n├── global/              # Global endpoint tests\n├── multi-instance/      # Multi-instance endpoint tests\n├── single-instance/     # Legacy endpoint tests\n├── postman_collection.json # Postman collection\n└── README.md           # API documentation\n\nauth/                    # Baileys authentication files\nlogs/                    # Application logs\nprisma/                  # Prisma database schema\n├── schema.prisma       # Database schema definition\ntests/                   # Test files\n├── database tests and setup\n```\n\n## Environment Variables\n\nConfigure the following environment variables in your `.env` file:\n\n### Required Variables\n\n```bash\n# Server Configuration\nPORT=3000                    # Port number for the server (default: 3000)\nNODE_ENV=production          # Environment mode: development, production\n\n# Database Configuration (Required for Multi-Instance Mode)\nDATABASE_URL=\"mongodb://localhost:27017/whisper-api\"\n                            # MongoDB connection string for Prisma\n                            # Format: mongodb://[username:password@]host[:port]/database\n                            # Example: mongodb://user:pass@localhost:27017/whisper-api\n\n# WhatsApp Configuration\nWHATSAPP_MODE=multi         # Operational mode: single, multi, both\n                            # - single: Legacy single-instance only\n                            # - multi: Multi-instance management only (default)\n                            # - both: Hybrid mode\n\n# Logging Configuration\nLOG_LEVEL=info              # Logging level: error, warn, info, debug\nDEBUG=true                  # Enable verbose debug output: true, false\n```\n\n### Environment Variable Details\n\n| Variable | Description | Default | Required |\n|----------|-------------|---------|----------|\n| `PORT` | Server port number | `3000` | No |\n| `NODE_ENV` | Application environment | `production` | No |\n| `DATABASE_URL` | MongoDB connection string | - | Yes (for multi-instance) |\n| `WHATSAPP_MODE` | Operational mode | `multi` | No |\n| `LOG_LEVEL` | Logging verbosity | `info` | No |\n| `DEBUG` | Debug mode toggle | `false` | No |\n\n### Mode Configuration\n\nThe `WHATSAPP_MODE` variable determines which endpoints are available:\n\n- **`single`**: Only legacy single-instance endpoints (`/api/v1/ping`, `/api/v1/message`, etc.)\n- **`multi`**: Only multi-instance endpoints (`/api/v1/instances/*`, webhooks, etc.)\n- **`both`**: All endpoints available (recommended for development)\n\n### Database Setup\n\nFor 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.\n\n**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.\n\n#### Option 1: MongoDB Atlas (Recommended)\n\nMongoDB Atlas provides free-tier clusters with replica sets enabled by default. This is the easiest and most reliable way to get started.\n\n1.  **Create a free cluster** on [MongoDB Atlas](https://www.mongodb.com/cloud/atlas).\n2.  **Get your connection string** (e.g., `mongodb+srv://user:pass@cluster.mongodb.net/whisper-api`).\n3.  **Update `DATABASE_URL`** in your `.env` file.\n\n#### Option 2: Local Docker with Replica Set\n\nYou can run a local MongoDB replica set using the provided Docker Compose file. This is ideal for development and testing.\n\n1.  **Ensure you have Docker and Docker Compose installed.**\n2.  **Run the following command** to start a single-node replica set:\n\n    ```bash\n    docker-compose up -d\n    ```\n\n3.  **Update your `DATABASE_URL`** to use the local replica set:\n\n    ```bash\n    DATABASE_URL=\"mongodb://localhost:27017/whisper-api?replicaSet=rs0\u0026directConnection=true\"\n    ```\n\n4.  **Stop the replica set** when you're done:\n\n    ```bash\n    docker-compose down\n    ```\n\nThis setup provides a complete, isolated environment for running the database with the required replica set configuration.\n\n## Phone Number Format\n\n- Format: `628123456789` (with country code 62 for Indonesia)\n- Numbers starting with `0` will be automatically formatted\n- Example: `08123456789` → `628123456789`\n\n## Group ID Format\n\n- Group IDs typically end with `@g.us`\n- Example: `120363042123456789@g.us`\n- Can be obtained from WhatsApp logs or other tools\n\n## Logging\n\n- Logs are stored in the `logs/` directory\n- `app.log` - all application logs\n- `error.log` - error logs only\n- Automatic log rotation (5MB per file, max 10 files)\n\n## Error Handling\n\nThe API returns standardized error responses:\n\n```json\n{\n  \"success\": false,\n  \"error\": \"Error type\",\n  \"message\": \"Detailed error message\",\n  \"timestamp\": \"2025-07-13T10:00:00.000Z\"\n}\n```\n\n## Deployment\n\n### Railway\n```bash\n# Install Railway CLI\nnpm install -g @railway/cli\n\n# Deploy\nrailway login\nrailway init\nrailway up\n```\n\n### Vercel\n```bash\n# Install Vercel CLI\nnpm install -g vercel\n\n# Deploy\nvercel --prod\n```\n\n### Render\n1. Connect your GitHub repository\n2. Set build command: `npm install`\n3. Set start command: `npm start`\n4. Deploy\n\n### VPS/Traditional Hosting\n```bash\n# Using PM2 for process management\nnpm install -g pm2\npm2 start src/app.js --name whisper-api\npm2 startup\npm2 save\n```\n\n## Usage Examples\n\n### Using cURL\n\n```bash\n# Health check\ncurl -X GET http://localhost:3000/api/v1/ping\n\n# Send message\ncurl -X POST http://localhost:3000/api/v1/message \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"phoneNumber\":\"628123456789\",\"message\":\"Hello World!\"}'\n\n# Check status\ncurl -X GET http://localhost:3000/api/v1/status\n```\n\n### Using JavaScript/Node.js\n\n```javascript\nconst axios = require('axios');\n\n// Send message\nconst sendMessage = async () =\u003e {\n  try {\n    const response = await axios.post('http://localhost:3000/api/v1/message', {\n      phoneNumber: '628123456789',\n      message: 'Hello from Whisper API!'\n    });\n    console.log(response.data);\n  } catch (error) {\n    console.error(error.response.data);\n  }\n};\n```\n\n## Notes\n\n### General Notes\n- The API supports three operational modes: `single`, `multi`, and `both` (hybrid)\n- Check current mode with `GET /api/v1/mode` before using specific endpoints\n- Keep the server running to maintain WhatsApp connections\n- All API responses follow a consistent format with `success`, `data`, and `message` fields\n\n### Single Instance Mode\n- QR code appears in terminal on first run or after logout\n- WhatsApp session is stored in the `auth/` directory\n- Don't delete the `auth/` folder to maintain session\n- Service will automatically reconnect if disconnected\n- Only one WhatsApp connection can be active at a time\n\n### Multi-Instance Mode\n- Requires MongoDB database connection for instance management\n- Each instance has its own authentication state stored in the database\n- QR codes are retrieved via API endpoints (`/api/v1/instances/{phone}/qr`)\n- Multiple WhatsApp instances can run simultaneously\n- Instance data persists between server restarts\n- Webhooks can be configured per instance for real-time notifications\n\n### Webhooks\n- Only available in multi-instance mode\n- Configure webhooks per instance for different events\n- Supported events: `message_received`, `message_sent`, `connection_status`, etc.\n- Webhook URLs should be publicly accessible HTTPS endpoints\n\n### Database\n- MongoDB is required for multi-instance functionality\n- Prisma ORM handles database operations\n- Run `npx prisma db push` to sync schema changes\n- Database stores instances, webhooks, messages, and logs\n\n## Common Issues\n\n### 1. QR Code Issues\n\n#### Single Instance Mode\n- QR code not appearing in terminal: Delete the `auth/` folder and restart the application\n- QR code expired: Restart the server to generate a new QR code\n- Authentication failed: Clear the `auth/` folder and scan a fresh QR code\n\n#### Multi-Instance Mode\n- QR code not generated: Check if instance exists with `GET /api/v1/instances/{phone}/status`\n- QR code endpoint returns error: Ensure the instance is in `pending` or `disconnected` state\n- QR code expired: Call `POST /api/v1/instances/{phone}/restart` to generate a new one\n\n### 2. Connection and Message Issues\n\n#### Single Instance Mode\n- Connection lost: Check status with `GET /api/v1/status` and restart if needed\n- Messages not sending: Verify connection status and phone number format (628xxxxxxxxx)\n- Service disconnected: Check logs and restart the application\n\n#### Multi-Instance Mode\n- Instance not connecting: Check instance status with `GET /api/v1/instances/{phone}/status`\n- Messages failing: Ensure instance is in `connected` state before sending\n- Multiple instances failing: Check database connection and MongoDB availability\n- Webhook not receiving events: Verify webhook URL is accessible and uses HTTPS\n\n### 3. Database Issues (Multi-Instance Mode)\n- Connection failed: Verify `DATABASE_URL` in `.env` file\n- Schema out of sync: Run `npx prisma db push` to update database schema\n- Migration errors: Run `npx prisma generate` followed by `npx prisma db push`\n- MongoDB not accessible: Ensure MongoDB is running and accessible at the specified URL\n\n### 4. Server and Configuration Issues\n- Port already in use: Change `PORT` in `.env` or kill existing processes with `lsof -ti:3000 | xargs kill -9`\n- Wrong operational mode: Check `WHATSAPP_MODE` in `.env` and restart server\n- Environment variables not loaded: Ensure `.env` file exists and is properly formatted\n- Service instability: Check logs in `logs/` directory for detailed error information\n\n### 5. Performance Issues\n- High memory usage: Monitor instance count and consider restarting instances periodically\n- Slow response times: Check database performance and consider adding indexes\n- Rate limiting: WhatsApp may limit message sending; implement delays between messages\n- Log file size: Configure log rotation or clear old logs from `logs/` directory\n\n### 6. Development and Testing Issues\n- API endpoints not working: Verify the correct mode is set and endpoints are available\n- CORS errors: Configure CORS settings if accessing from browser applications\n- Authentication errors: Ensure proper headers and request format as per API documentation\n- Webhook testing: Use tools like ngrok for local webhook testing with public HTTPS URLs\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Disclaimer\n\nThis project is for educational and development purposes. Please ensure you comply with WhatsApp's Terms of Service when using this API.\n\n## Support\n\nIf you found this project helpful, please give it a ⭐ star!\n\nFor issues and questions, please create an issue in the GitHub repository.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fibnusyawall%2Fwhisper-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fibnusyawall%2Fwhisper-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fibnusyawall%2Fwhisper-api/lists"}