natureco-whatsapp-service

NatureCo WhatsApp Service

Standalone Node.js service for WhatsApp integration using whatsapp-web.js. Designed to be deployed on Railway, Render, or any Node.js hosting platform.

Features

• QR Code Generation - Real-time QR code streaming via SSE
• Session Management - Multiple bot sessions with LocalAuth
• Status Monitoring - Check connection status for any session
• Graceful Disconnect - Clean session termination
• Production Ready - Optimized for Railway/Render deployment

API Endpoints

POST /connect

Create a new WhatsApp session and generate QR code.

Request:

{
  "bot_id": "bot_123"
}

Response:

{
  "session_id": "whatsapp_bot_123_1234567890",
  "bot_id": "bot_123",
  "status": "pending",
  "message": "WhatsApp session created. Use SSE endpoint to receive QR code.",
  "sse_endpoint": "/qr/whatsapp_bot_123_1234567890"
}

GET /qr/:session_id

Server-Sent Events (SSE) endpoint for real-time QR code streaming.

Events:

• connected - Initial connection established
• qr - QR code generated (base64 data URL)
• ready - WhatsApp authenticated and ready
• error - Authentication or connection error
• disconnected - Session disconnected

Example:

const eventSource = new EventSource('https://whatsapp.natureco.me/qr/session_id');

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  
  if (data.type === 'qr') {
    // Display QR code: data.qr (base64 data URL)
    console.log('QR Code:', data.qr);
  }
  
  if (data.type === 'ready') {
    console.log('WhatsApp connected!');
    eventSource.close();
  }
};

GET /status/:session_id

Get current status of a WhatsApp session.

Response:

{
  "session_id": "whatsapp_bot_123_1234567890",
  "bot_id": "bot_123",
  "status": "connected",
  "created_at": "2024-01-01T00:00:00.000Z",
  "connected_at": "2024-01-01T00:01:00.000Z",
  "disconnected_at": null,
  "has_qr": true,
  "client_active": true,
  "error": null,
  "disconnect_reason": null
}

Status values:

• pending - Waiting for QR scan
• authenticated - QR scanned, authenticating
• connected - Fully connected and ready
• disconnected - Session ended
• auth_failed - Authentication failed
• error - Error occurred

POST /disconnect

Disconnect and destroy a WhatsApp session.

Request:

{
  "session_id": "whatsapp_bot_123_1234567890"
}

Response:

{
  "success": true,
  "message": "WhatsApp session disconnected",
  "session_id": "whatsapp_bot_123_1234567890"
}

GET /sessions

List all active sessions (admin endpoint).

Response:

{
  "total": 2,
  "sessions": [
    {
      "session_id": "whatsapp_bot_123_1234567890",
      "bot_id": "bot_123",
      "status": "connected",
      "created_at": "2024-01-01T00:00:00.000Z",
      "connected_at": "2024-01-01T00:01:00.000Z"
    }
  ]
}

Installation

# Install dependencies
npm install

# Copy environment file
cp .env.example .env

# Start development server
npm run dev

# Start production server
npm start

Environment Variables

PORT=3000
NODE_ENV=production
API_SECRET=your-secret-key-here

Deployment

Railway

• Create new project on Railway
• Connect GitHub repository
• Set environment variables
• Deploy automatically

railway.json:

{
  "$schema": "https://railway.app/railway.schema.json",
  "build": {
    "builder": "NIXPACKS"
  },
  "deploy": {
    "startCommand": "npm start",
    "restartPolicyType": "ON_FAILURE",
    "restartPolicyMaxRetries": 10
  }
}

Render

• Create new Web Service
• Connect GitHub repository
• Build Command: npm install
• Start Command: npm start
• Set environment variables
• Deploy

render.yaml:

services:
  - type: web
    name: natureco-whatsapp
    env: node
    buildCommand: npm install
    startCommand: npm start
    envVars:
      - key: NODE_ENV
        value: production

Custom Domain

Point whatsapp.natureco.me to your deployment:

Railway: Settings → Networking → Custom Domain Render: Settings → Custom Domain

Architecture

┌─────────────────┐
│   NatureCo CLI  │
│   or Worker     │
└────────┬────────┘
         │
         │ HTTP/SSE
         ▼
┌─────────────────────────┐
│  WhatsApp Service       │
│  (Express + SSE)        │
└────────┬────────────────┘
         │
         │ whatsapp-web.js
         ▼
┌─────────────────────────┐
│  WhatsApp Web           │
│  (Puppeteer + Chrome)   │
└─────────────────────────┘

Production Considerations

• Memory: WhatsApp sessions use ~200-300MB each (Chromium)
• Storage: LocalAuth stores session data in .wwebjs_auth/
• Scaling: Use Redis for session storage in multi-instance setup
• Monitoring: Add health checks and logging (e.g., Sentry)
• Security: Add API authentication middleware

Troubleshooting

QR Code not generating:

• Check Puppeteer dependencies are installed
• Ensure sufficient memory (min 512MB)
• Check logs for Chromium errors

Session disconnects:

• WhatsApp Web sessions expire after ~2 weeks of inactivity
• Implement reconnection logic in your application

Multiple instances:

• Use shared storage (S3, Redis) for .wwebjs_auth/
• Implement session locking to prevent conflicts

License

MIT © NatureCo

Service URL: https://whatsapp.natureco.me Version: 1.0.0 Node.js: >=18.0.0