WhatSignal is a bridge service that enables one-to-one chat between WhatsApp and Signal. It forwards messages (text, images, videos, audio, reactions) between the platforms while maintaining conversation context, supporting replies, and providing intelligent auto-reply functionality.
- WhatsApp ↔ Signal one-to-one bridge with preserved context (replies, quotes, metadata)
- Group chat support: WhatsApp groups → Signal messages & reply support
- Smart contacts: show names (not just numbers), warm cache at startup, periodic refresh, graceful fallback
- Media support: images, videos, documents, voice notes
- Status support: typing indicators, seen status
- Message extras: reactions, auto‑reply to last sender, delivery status tracking
- Security by default: encrypted storage, webhook auth/validation, configurable retention, automated cleanup
- Operational hygiene: health endpoint, structured JSON logs, graceful retries
- Developer‑friendly: Dockerized, type‑safe handling, comprehensive tests (>80% coverage)
To use WhatSignal, you must have:
- WhatsApp Number: Registered and active, activated as a session on WAHA.
- Signal Bridge Number: Dedicated for the bridge, used by Signal-CLI, and different from the destination number.
- Signal Destination Number: The final recipient, typically on your mobile or desktop Signal app. This must not be the same as the bridge number.
One-liner deployment (no source code needed):
curl -fsSL https://raw.githubusercontent.com/bikemazzell/whatsignal/main/scripts/deploy.sh | bash📋 Then follow the Quick Start Checklist for complete setup steps.
Manual deployment:
# Download deployment script
curl -fsSL https://raw.githubusercontent.com/bikemazzell/whatsignal/main/scripts/deploy.sh -o deploy.sh
chmod +x deploy.sh
./deploy.sh
# Configure your settings
cd whatsignal-deploy
nano .env # API keys and secrets
nano config.json # Signal/WhatsApp phone numbers
# Start services
docker compose up -d
# Check status
docker compose ps
curl http://localhost:8082/health📖 For detailed deployment instructions, see: Deployment Guide
For development or customization:
git clone https://github.com/bikemazzell/whatsignal.git
cd whatsignal
./scripts/setup.sh # Creates .env and config.json
make docker-up # Build and start all servicesmake docker-up # Start all services
make docker-down # Stop all services
make docker-logs # Follow logs
make docker-status # Check service status
make docker-restart # Restart services
make docker-clean # Clean up everythingServices won't start:
# Check service status
make docker-status
# View logs for issues
make docker-logs
# Restart services
make docker-restartPort conflicts:
- WhatSignal: 8082
- WAHA: 3000
- Signal-CLI: 8080
Clean slate restart:
make docker-clean # Removes all data!
./scripts/setup.sh # Recreate config
make docker-up # Start fresh- Quick Start Checklist - Step-by-step deployment checklist
- Deployment Guide - Complete deployment instructions
- Configuration Guide - Configuration options and settings
- Security Guide - Encryption and security features
- Development Guide - Contributing and development setup
- Technical Requirements - Design specifications
- Release Process - Version management and releases
- Fork the repository
- Create your feature branch
- Write tests for new functionality
- Update documentation
- Submit pull request
See Development Guide for detailed instructions.
This project is licensed under the MIT License - see the LICENSE file for details.
- Waha for the WhatsApp HTTP API
- signal-cli-rest-api for the Signal CLI interface