History

Darren Clarke 3d8f794cab Add user ID support for Baileys 7 LIDs and Signal UUIDs Baileys 7 uses LIDs (Linked IDs) instead of phone numbers in remoteJid for some messages. This caused messages to be matched to wrong tickets because the LID was used as the sender identifier. This commit adds proper support for both phone numbers and user IDs across WhatsApp and Signal channels. Changes: Database: - Add migration for whatsapp_user_id and signal_user_id fields on users table Zammad controllers: - Update user lookup with 3-step fallback: phone → dedicated user_id field → user_id in phone field (legacy) - Store user IDs in dedicated fields when available - Update phone field when we receive actual phone number for legacy records - Fix redundant condition in Signal controller Bridge services: - Extract both phone (from senderPn/participantPn) and LID (from remoteJid) - Send both identifiers to Zammad via webhooks - Use camelCase (userId) in bridge-whatsapp, convert to snake_case (user_id) in bridge-worker for Zammad compatibility Baileys 7 compliance: - Remove broken loadAllUnreadMessages() call (removed in Baileys 7) - Return descriptive error directing users to use webhooks instead Misc: - Add docs/ to .gitignore		2026-01-15 13:08:56 +01:00
..
src	Add user ID support for Baileys 7 LIDs and Signal UUIDs	2026-01-15 13:08:56 +01:00
docker-entrypoint.sh	WhatsApp/Signal/Formstack/admin updates	2025-11-21 14:55:28 +01:00
Dockerfile	WhatsApp/Signal/Formstack/admin updates	2025-11-21 14:55:28 +01:00
jest.config.json	Add bridge-whatsapp	2024-05-07 14:16:01 +02:00
package.json	Bump version to 3.4.0-beta.4	2026-01-14 11:33:11 +01:00
README.md	WhatsApp/Signal/Formstack/admin updates	2025-11-21 14:55:28 +01:00
tsconfig.json	Update Baileys to 7RC	2026-01-14 11:00:41 +01: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