WhatsApp API Server

A comprehensive Express.js API server for WhatsApp Web integration with student management features, built with whatsapp-web.js.

🚀 Features

WhatsApp Integration: Full WhatsApp Web API with QR code authentication
REST API: Send single and bulk messages with media support
Web Interface: User-friendly web dashboard for QR authentication and messaging
Student Management: Bulk messaging for educational institutions
Real-time Updates: WebSocket integration for live QR codes and status updates
Media Support: Send images, documents, and other media files
API Authentication: Secure API key-based authentication
Rate Limiting: Protection against API abuse
Docker Support: Complete containerization with Docker Compose
Production Ready: SSL support, Nginx reverse proxy, and security hardening

📋 Prerequisites

Node.js 18+ or Docker
Chrome/Chromium browser (for WhatsApp Web)
(Optional) Redis for session storage

🛠️ Installation

Option 1: Appwrite Cloud Deployment (Recommended)

Deploy to Appwrite Cloud for serverless, scalable hosting:

Install Appwrite CLI:
```
npm install -g appwrite-cli
```

Configure for Appwrite:

cp .env.appwrite .env
# Edit .env with your Appwrite project details

Build and Deploy:

npm run build:appwrite
appwrite deploy function

📋 Complete Appwrite Deployment Guide

Option 2: Docker Deployment

Clone the repository:
```
git clone <your-repo-url>
cd wwebjs-bot
```
Make deployment script executable:
```
chmod +x deploy.sh
```

Configure environment:

cp .env.example .env
# Edit .env with your configuration

Deploy the application:
```
./deploy.sh
```

Option 3: Manual Installation

Install dependencies:
```
npm install
```

Configure environment:

cp .env.example .env
# Edit .env with your settings

Start the application:

# Development
npm run dev

# Production
npm start

🌐 API Endpoints

Authentication

All API endpoints require an API key in the header:

Authorization: Bearer YOUR_API_KEY

Core Endpoints

1. Health Check

GET /health

2. WhatsApp Status

GET /api/whatsapp/status

3. Send Message

POST /api/whatsapp/send-message
Content-Type: application/json

{
  "number": "1234567890",
  "message": "Hello from WhatsApp API!"
}

4. Send Bulk Messages

POST /api/whatsapp/send-bulk
Content-Type: application/json

{
  "recipients": [
    {
      "number": "1234567890",
      "name": "John Doe",
      "message": "Hello John!"
    },
    {
      "number": "0987654321", 
      "name": "Jane Smith",
      "message": "Hello Jane!"
    }
  ]
}

5. Send Media Message

POST /api/whatsapp/send-media
Content-Type: multipart/form-data

number=1234567890
caption=Check this out!
media=[file upload]

6. Get Contacts

GET /api/whatsapp/contacts

🖥️ Web Interface

Access the web interface at:

HTTP: http://localhost
HTTPS: https://localhost

Features:

QR code authentication
Real-time connection status
Send individual messages
Bulk message management
File upload for media messages

📊 Postman Collection

Import the Postman collection from the postman/ directory:

Open Postman
Import postman/WhatsApp_API_Collection.json
Import environment from postman/environments/
Set your API key in the environment variables

🐳 Docker Commands

# Deploy application
./deploy.sh

# Start development environment
./deploy.sh dev

# View logs
./deploy.sh logs

# Stop services  
./deploy.sh stop

# Restart services
./deploy.sh restart

# Clean up (remove all containers and images)
./deploy.sh clean

# Create backup
./deploy.sh backup

🔧 Configuration

Environment Variables

Key configuration options in .env:

# Server
NODE_ENV=production
PORT=3000
API_KEY=your-api-key-here

# WhatsApp
WHATSAPP_SESSION_NAME=default-session
WHATSAPP_HEADLESS=true

# Security
RATE_LIMIT_MAX_REQUESTS=100
SSL_ENABLED=false

# Features
FEATURE_BULK_MESSAGING=true
FEATURE_MEDIA_MESSAGES=true
FEATURE_STUDENT_MANAGEMENT=true

Docker Compose Services

whatsapp-api: Main application server
redis: Session storage and caching
nginx: Reverse proxy with SSL termination

Appwrite Cloud Services

Functions: Serverless WhatsApp API execution
Database: Session, message, and contact storage
Storage: Media file uploads and management
CDN: Global content delivery

🔒 Security Features

API key authentication
Rate limiting protection
CORS configuration
Security headers (Helmet.js)
Input validation and sanitization
File upload restrictions
SSL/TLS support

📁 Project Structure

wwebjs-bot/
├── src/
│   ├── config/          # Configuration files
│   ├── middleware/      # Express middleware
│   ├── routes/          # API route handlers
│   └── services/        # Business logic services
├── public/              # Static web files
├── views/               # HTML templates
├── postman/             # API testing collection
├── ssl/                 # SSL certificates
├── uploads/             # File uploads
├── logs/                # Application logs
├── docker-compose.yml   # Production Docker setup
├── docker-compose.dev.yml # Development Docker setup
├── Dockerfile           # Container configuration
├── nginx.conf           # Nginx configuration
└── deploy.sh           # Deployment script

🚦 Getting Started

First Time Setup:
```
./deploy.sh
```
Access the web interface: Navigate to http://localhost
Scan QR Code: Use your phone's WhatsApp to scan the QR code

Test API: Use the Postman collection or curl:

curl -X POST http://localhost/api/whatsapp/send-message \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number":"1234567890","message":"Hello World!"}'

🔍 Monitoring & Logs

Application Logs: ./logs/app.log
Docker Logs: docker-compose logs -f
Health Check: GET /health
Status Check: GET /api/whatsapp/status

🎓 Student Management Features

Bulk messaging to student groups
Contact import/export
Message templates
Student data management
Personalized messaging

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

📝 License

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

⚠️ Disclaimer

This project is not officially affiliated with WhatsApp. Use responsibly and in accordance with WhatsApp's Terms of Service.

🆘 Support

Check the logs: ./deploy.sh logs
Review the health check: GET /health
Restart services: ./deploy.sh restart
Clean deployment: ./deploy.sh clean && ./deploy.sh

🔗 Useful Links

Made with ❤️ for educational institutions and developers

Security & Performance

Rate Limiting - Prevent API abuse
Input Validation - Comprehensive request validation
API Key Authentication - Optional API key protection
CORS Support - Configurable cross-origin requests
File Upload Validation - Secure media file handling

📋 Prerequisites

Node.js (v14 or higher)
Google Chrome browser installed
WhatsApp mobile app

🛠️ Installation

Clone or download the project:

git clone <repository-url>
cd wwebjs-bot

Install dependencies:
```
npm install
```

Configure environment variables:

cp .env.example .env

Edit .env file as needed:

PORT=3000
HOST=localhost
API_KEY=your-optional-api-key
MESSAGE_DELAY=2000
MAX_BULK_MESSAGES=50

Start the server:

# Development mode with auto-reload
npm run dev

# Production mode
npm start

🌐 Usage

Web Interface

Open your browser and navigate to http://localhost:3000
Scan the QR code with your WhatsApp mobile app:
- Open WhatsApp on your phone
- Go to Settings → Linked Devices → Link a Device
- Scan the QR code displayed on the web interface
Once connected, you can send messages through the web interface

Postman Collection

A comprehensive Postman collection is included for API testing:

Import Collection:
- Import postman/WhatsApp-API-Collection.json
- Import postman/WhatsApp-API-Environment-Dev.json
Configure Environment:
- Set baseUrl to http://localhost:3000
- Set apiKey if using API key authentication
- Set testPhoneNumber to your test number
Start Testing:
- Begin with "Health Check" and "WhatsApp Status"
- Test message sending with various scenarios
- See postman/README.md for detailed instructions

API Endpoints

Authentication

If API_KEY is set in your environment, include it in requests:

# Header method
curl -H "X-API-Key: your-api-key" ...

# Query parameter method
curl "http://localhost:3000/api/whatsapp/status?apiKey=your-api-key"

Send Single Message

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

Send Bulk Messages

curl -X POST http://localhost:3000/api/whatsapp/send-bulk \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {"number": "+201234567890", "name": "Ahmed Ali", "studentId": "2023001", "class": "Grade 10A"},
      {"number": "+201234567891", "name": "Sara Mohamed", "studentId": "2023002", "class": "Grade 10A"}
    ],
    "message": "Dear {name}, your student ID {studentId} has been assigned to {class}.",
    "options": {"delay": 2000}
  }'

Send Media Message

curl -X POST http://localhost:3000/api/whatsapp/send-media \
  -F "number=+201234567890" \
  -F "message=Check out this document!" \
  -F "media=@/path/to/your/file.pdf"

Get Status

curl http://localhost:3000/api/whatsapp/status

Get QR Code

curl http://localhost:3000/api/whatsapp/qr

📁 Project Structure

wwebjs-bot/
├── app.js                 # Main application entry point
├── package.json          # Dependencies and scripts
├── .env.example          # Environment configuration template
├── README.md             # This file
├── postman/              # Postman collection and environments
│   ├── WhatsApp-API-Collection.json     # Postman collection
│   ├── WhatsApp-API-Environment-Dev.json   # Development environment
│   ├── WhatsApp-API-Environment-Prod.json  # Production environment
│   ├── test-scripts.js              # Automated test scripts
│   └── README.md                    # Postman documentation
├── src/
│   ├── config/
│   │   └── config.js     # Application configuration
│   ├── services/
│   │   └── whatsappService.js  # WhatsApp client service
│   ├── routes/
│   │   └── whatsapp.js   # API routes
│   ├── middleware/
│   │   ├── auth.js       # Authentication middleware
│   │   └── validation.js # Request validation
│   ├── utils/
│   │   └── logger.js     # Logging utility
│   └── server.js         # Express server setup
├── public/
│   ├── css/
│   │   └── styles.css    # Web interface styles
│   └── js/
│       └── main.js       # Client-side JavaScript
├── views/
│   └── index.html        # Web interface template
└── uploads/              # Media file uploads (auto-created)

🎓 Student Management Integration Examples

1. Class Announcements

const classAnnouncement = {
  "contacts": [
    {"number": "+201234567890", "name": "Ahmed Ali", "class": "Grade 10A"},
    {"number": "+201234567891", "name": "Sara Mohamed", "class": "Grade 10A"}
  ],
  "message": "Dear {name},\n\nImportant announcement for {class}:\n\nTomorrow's math exam has been postponed to next Friday. Please prepare accordingly.\n\nBest regards,\nSchool Administration"
}

2. Grade Notifications

const gradeNotification = {
  "contacts": [
    {"number": "+201234567890", "name": "Ahmed Ali", "studentId": "2023001", "grade": "A+"},
    {"number": "+201234567891", "name": "Sara Mohamed", "studentId": "2023002", "grade": "A"}
  ],
  "message": "Congratulations {name}!\n\nYour final grade for Mathematics is: {grade}\n\nStudent ID: {studentId}\n\nKeep up the excellent work!"
}

3. Parent Notifications

const parentNotification = {
  "contacts": [
    {"number": "+201234567892", "name": "Mohamed Ali", "studentName": "Ahmed Ali", "class": "Grade 10A"},
    {"number": "+201234567893", "name": "Fatima Mohamed", "studentName": "Sara Mohamed", "class": "Grade 10A"}
  ],
  "message": "Dear {name},\n\nThis is to inform you that your child {studentName} from {class} will have a parent-teacher meeting scheduled for next Tuesday at 3 PM.\n\nPlease confirm your attendance.\n\nThank you."
}

⚙️ Configuration Options

Environment Variables

Variable	Default	Description
`PORT`	3000	Server port
`HOST`	localhost	Server host
`API_KEY`	null	Optional API authentication key
`CORS_ORIGIN`	*	CORS allowed origins
`RATE_LIMIT_MAX`	100	Max requests per window
`MESSAGE_DELAY`	2000	Delay between bulk messages (ms)
`MAX_BULK_MESSAGES`	50	Maximum contacts in bulk operation
`CHROME_PATH`	auto-detected	Custom Chrome executable path

Message Template Placeholders

Placeholder	Description
`{name}`	Full name
`{firstName}`	First name
`{lastName}`	Last name
`{studentId}`	Student ID number
`{class}`	Class/grade level
`{grade}`	Academic grade

📚 API Reference

Response Format

All API responses follow this format:

{
  "success": true,
  "data": { ... },
  "message": "Operation completed successfully"
}

Error Response

{
  "success": false,
  "error": "Error type",
  "message": "Detailed error message"
}

Status Codes

200 - Success
400 - Bad Request (validation errors)
401 - Unauthorized (invalid API key)
404 - Not Found
429 - Too Many Requests (rate limit exceeded)
500 - Internal Server Error

🔧 Troubleshooting

Common Issues

QR Code not displaying:
- Check if Chrome is installed and accessible
- Verify Chrome executable path in configuration
- Restart the application
Messages not sending:
- Ensure WhatsApp client is connected (green status)
- Check phone number format (include country code)
- Verify rate limits aren't exceeded
Authentication failures:
- Clear browser cache and cookies
- Restart the application
- Re-scan QR code
File upload issues:
- Check file size (max 10MB by default)
- Verify file type is supported
- Ensure uploads directory has write permissions

📝 Development

Running in Development Mode

npm run dev

Adding New Features

Create feature branch
Add routes in src/routes/
Update service in src/services/whatsappService.js
Add validation in src/middleware/validation.js
Update web interface if needed
Test thoroughly

Logging

Logs are automatically written to logs/ directory with daily rotation.

🔒 Security Considerations

Always use HTTPS in production
Set strong API keys
Configure CORS properly
Implement rate limiting
Validate all inputs
Keep dependencies updated
Monitor logs for suspicious activity

📄 License

This project is licensed under the ISC License.

🤝 Support

For issues and questions:

Check the troubleshooting section
Review API documentation
Check browser console for errors
Verify network connectivity

🎉 Acknowledgments

Built with whatsapp-web.js
UI powered by Bootstrap 5
Real-time updates via Socket.IO

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
postman		postman
public		public
scripts		scripts
src		src
views		views
.env.appwrite		.env.appwrite
.env.example		.env.example
.gitignore		.gitignore
API-KEY-SETUP.md		API-KEY-SETUP.md
APPWRITE_DEPLOYMENT.md		APPWRITE_DEPLOYMENT.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
appwrite.json		appwrite.json
deploy.sh		deploy.sh
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.yml		docker-compose.yml
main.js		main.js
nginx.conf		nginx.conf
package-lock.json		package-lock.json
package.json		package.json

License

omarashrafdev/wwebjs-bot

Folders and files

Latest commit

History

Repository files navigation

WhatsApp API Server

🚀 Features

📋 Prerequisites

🛠️ Installation

Option 1: Appwrite Cloud Deployment (Recommended)

Option 2: Docker Deployment

Option 3: Manual Installation

🌐 API Endpoints

Authentication

Core Endpoints

1. Health Check

2. WhatsApp Status

3. Send Message

4. Send Bulk Messages

5. Send Media Message

6. Get Contacts

🖥️ Web Interface

📊 Postman Collection

🐳 Docker Commands

🔧 Configuration

Environment Variables

Docker Compose Services

Appwrite Cloud Services

🔒 Security Features

📁 Project Structure

🚦 Getting Started

🔍 Monitoring & Logs

🎓 Student Management Features

🤝 Contributing

📝 License

⚠️ Disclaimer

🆘 Support

🔗 Useful Links

Security & Performance

📋 Prerequisites

🛠️ Installation

🌐 Usage

Web Interface

Postman Collection

API Endpoints

Authentication

Send Single Message

Send Bulk Messages

Send Media Message

Get Status

Get QR Code

📁 Project Structure

🎓 Student Management Integration Examples

1. Class Announcements

2. Grade Notifications

3. Parent Notifications

⚙️ Configuration Options

Environment Variables

Message Template Placeholders

📚 API Reference

Response Format

Error Response

Status Codes

🔧 Troubleshooting

Common Issues

📝 Development

Running in Development Mode

Adding New Features

Logging

🔒 Security Considerations

📄 License

🤝 Support

🎉 Acknowledgments

About

Resources

License

Contributing

Security policy

Uh oh!

Packages