Zync Nest Message Module

A comprehensive NestJS module for WhatsApp messaging integration with QR code authentication support.

Features

• ✅ WhatsApp Web Integration - Full WhatsApp Web.js integration
• ✅ Multi-Session Management - Support for multiple WhatsApp sessions
• ✅ QR Code Authentication - Browser-based QR code display for authentication
• ✅ Session Management - Create, manage, and monitor WhatsApp sessions
• ✅ Message Sending - Send text and media messages
• ✅ Auto Cleanup - Automatic cleanup of inactive sessions
• ✅ REST API - Complete REST API for WhatsApp operations
• ✅ GraphQL Support - GraphQL integration ready
• ✅ Type Safety - Full TypeScript support

Quick Start

Installation

npm install zync-nest-message-module
# or
pnpm add zync-nest-message-module

Basic Usage

import { Module } from '@nestjs/common';
import { WhatsappModule } from 'zync-nest-message-module';

@Module({
  imports: [
    WhatsappModule,
    // ... other modules
  ],
})
export class AppModule {}

Create and Authenticate a Session

1. Create a session:

POST /whatsapp/sessions
{
  "sessionId": "my-session",
  "name": "My WhatsApp Session",
  "autoInit": true
}

2. Get QR code for authentication:

<!-- Display QR code as image -->
<img src="http://localhost:3000/whatsapp/sessions/my-session/qr" alt="WhatsApp QR Code">

3. Check authentication status:

GET /whatsapp/sessions/my-session

4. Send a message:

POST /whatsapp/send-message
{
  "sessionId": "my-session",
  "to": "[email protected]",
  "message": "Hello from WhatsApp!"
}

🔥 New QR Code Features

Browser QR Code Display

• Get QR codes as PNG images: GET /whatsapp/sessions/{sessionId}/qr
• Get QR code text data: GET /whatsapp/sessions/{sessionId}/qr-text
• Real-time session status with QR code information
• Automatic QR code cleanup after authentication

Demo

Open whatsapp-qr-demo.html in your browser for a complete working example.

API Endpoints

Session Management

• POST /whatsapp/sessions - Create a new session
• GET /whatsapp/sessions - Get all sessions
• GET /whatsapp/sessions/{id} - Get session status
• GET /whatsapp/sessions/{id}/qr - Get QR code image
• GET /whatsapp/sessions/{id}/qr-text - Get QR code text
• POST /whatsapp/sessions/{id}/initialize - Initialize session
• POST /whatsapp/sessions/{id}/restart - Restart session
• DELETE /whatsapp/sessions/{id} - Destroy session
• DELETE /whatsapp/sessions - Destroy all sessions

Messaging

• POST /whatsapp/send-message - Send text message
• POST /whatsapp/send-media - Send media message
• POST /whatsapp/legacy/send-message - Legacy endpoint

System

• GET /whatsapp/system/status - Get system status
• GET /whatsapp/system/stats - Get session statistics

Configuration

// app.module.ts
import { ConfigModule } from '@nestjs/config';

@Module({
  imports: [
    ConfigModule.forRoot({
      envFilePath: '.env',
    }),
    WhatsappModule,
  ],
})
export class AppModule {}

Environment Variables

# WhatsApp Configuration
WHATSAPP_MAX_SESSIONS=10
WHATSAPP_SESSION_TIMEOUT=1800000  # 30 minutes
WHATSAPP_SESSION_ID=session-1     # Default session ID
CHROME_EXECUTABLE_PATH=/path/to/chrome  # Optional Chrome path

Advanced Usage

Service Injection

import { Injectable } from '@nestjs/common';
import { WhatsappService } from 'zync-nest-message-module';

@Injectable()
export class MyService {
  constructor(private readonly whatsappService: WhatsappService) {}

  async sendWelcomeMessage(phoneNumber: string) {
    return await this.whatsappService.sendMessage({
      sessionId: 'my-session',
      to: `${phoneNumber}@c.us`,
      message: 'Welcome to our service!'
    });
  }

  async getSessionQRCode(sessionId: string) {
    const status = this.whatsappService.getSessionStatus(sessionId);
    return status?.qrCode;
  }
}

React Integration Example

import React, { useState, useEffect } from 'react';

const WhatsAppAuth = () => {
  const [qrImageUrl, setQrImageUrl] = useState(null);
  const [isAuthenticated, setIsAuthenticated] = useState(false);

  useEffect(() => {
    // Create session
    fetch('/whatsapp/sessions', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        sessionId: 'react-session',
        name: 'React Session',
        autoInit: true
      })
    });

    // Poll for QR code and status
    const interval = setInterval(async () => {
      const statusResponse = await fetch('/whatsapp/sessions/react-session');
      const status = await statusResponse.json();
      
      if (status.isAuthenticated) {
        setIsAuthenticated(true);
        setQrImageUrl(null);
      } else if (status.qrCode) {
        const qrResponse = await fetch('/whatsapp/sessions/react-session/qr');
        if (qrResponse.ok) {
          const blob = await qrResponse.blob();
          setQrImageUrl(URL.createObjectURL(blob));
        }
      }
    }, 2000);

    return () => clearInterval(interval);
  }, []);

  return (
    <div>
      {isAuthenticated ? (
        <p>✅ WhatsApp Connected!</p>
      ) : qrImageUrl ? (
        <img src={qrImageUrl} alt="WhatsApp QR Code" />
      ) : (
        <p>Generating QR code...</p>
      )}
    </div>
  );
};

Documentation

• WhatsApp QR Code Guide - Detailed QR code integration guide
• Development Guide - Development and contribution guide

Dependencies

• whatsapp-web.js - WhatsApp Web client
• puppeteer - Browser automation
• qrcode - QR code generation
• qrcode-terminal - Terminal QR code display

Requirements

• Node.js 16+
• Chrome/Chromium browser
• WhatsApp account

License

ISC

Contributing

1. Fork the repository
2. Create your 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

Support

For support and questions, please open an issue in the GitHub repository.

Made with ❤️ by the Zync team