link-stack/apps/bridge-whatsapp

Bridge WhatsApp

WhatsApp integration service for the CDR Link communication bridge system.

Overview

Bridge WhatsApp provides a REST API for sending and receiving WhatsApp messages using the Baileys library (WhatsApp Web API). It handles bot session management, message routing, and media processing for WhatsApp communication channels.

Features

• Bot Management: Register and manage multiple WhatsApp bot sessions
• Message Handling: Send and receive text messages with formatting
• Media Support: Handle images, documents, audio, and video files
• QR Code Authentication: Web-based WhatsApp authentication
• REST API: Simple HTTP endpoints for integration

Development

Prerequisites

• Node.js >= 20
• npm >= 10
• PostgreSQL database (for bot configuration)

Setup

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run development server
npm run dev

# Start production server
npm run start

Environment Variables

• PORT - Server port (default: 5000)
• DATABASE_URL - PostgreSQL connection string (optional)
• Additional WhatsApp-specific configuration as needed

Available Scripts

• npm run build - Compile TypeScript
• npm run dev - Development mode with auto-reload
• npm run start - Start production server

API Endpoints

Bot Management

• POST /api/bots/:token - Register/initialize a bot
• GET /api/bots/:token - Get bot status and QR code

Messaging

• POST /api/bots/:token/send - Send a message
• POST /api/bots/:token/receive - Webhook for incoming messages

Request/Response Format

Send Message

{
  "to": "1234567890@s.whatsapp.net",
  "message": "Hello World",
  "media": {
    "url": "https://example.com/image.jpg",
    "type": "image"
  }
}

Receive Message Webhook

{
  "from": "1234567890@s.whatsapp.net",
  "message": "Hello",
  "timestamp": "2024-01-01T00:00:00Z",
  "media": {
    "url": "https://...",
    "type": "image",
    "mimetype": "image/jpeg"
  }
}

Architecture

Server Framework

Built with Hapi.js for:

• Route validation
• Plugin architecture
• Error handling
• Request lifecycle

WhatsApp Integration

Uses @whiskeysockets/baileys:

• WhatsApp Web protocol
• Multi-device support
• Message encryption
• Media handling

Session Management

• File-based session storage
• Automatic reconnection
• QR code regeneration
• Session cleanup

Media Handling

Supported media types:

• Images: JPEG, PNG, GIF
• Documents: PDF, DOC, DOCX
• Audio: MP3, OGG, WAV
• Video: MP4, AVI

Media is processed and uploaded before sending.

Error Handling

• Connection errors trigger reconnection
• Invalid sessions regenerate QR codes
• API errors return appropriate HTTP status codes
• Comprehensive logging for debugging

Security

• Token-based bot authentication
• Message validation
• Rate limiting (configurable)
• Secure session storage

Integration

Designed to work with:

• bridge-worker: Processes WhatsApp message jobs
• bridge-frontend: Manages bot configuration
• External webhooks for message routing

Docker Support

# Build image
docker build -t link-stack/bridge-whatsapp .

# Run container
docker run -p 5000:5000 link-stack/bridge-whatsapp

Testing

While test configuration exists (jest.config.json), tests should be implemented for:

• API endpoint validation
• Message processing logic
• Session management
• Error scenarios