History

Darren Clarke d2a3c71bcd feat: Add attachment support for Signal and WhatsApp channels - Signal: Use base64Attachments field in signal-cli-rest-api - WhatsApp: Implement Baileys attachment sending for images, videos, audio, and documents - Both channels retrieve attachments from Zammad Store model - Support multiple attachments per message		2025-09-02 10:55:04 +02:00
..
src	feat: Add attachment support for Signal and WhatsApp channels	2025-09-02 10:55:04 +02:00
docker-entrypoint.sh	Add Signal and Whatsapp Docker CI	2024-05-15 10:27:14 +02:00
Dockerfile	Update deps and Docker images	2024-09-27 11:22:45 +02:00
jest.config.json	Add bridge-whatsapp	2024-05-07 14:16:01 +02:00
package.json	fix: Add missing @link-stack/logger dependency to bridge-whatsapp	2025-08-20 12:08:26 +02:00
README.md	Add basic READMEs	2025-05-23 13:20:07 +02:00
tsconfig.json	CSRF refresh fixes	2024-08-14 13:03:50 +02:00

README.md

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