173 lines
3.4 KiB
Markdown
173 lines
3.4 KiB
Markdown
|
# 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
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# 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
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"to": "1234567890@s.whatsapp.net",
|
||
|
|
"message": "Hello World",
|
||
|
|
"media": {
|
||
|
|
"url": "https://example.com/image.jpg",
|
||
|
|
"type": "image"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
#### Receive Message Webhook
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"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
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# 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
|