Waaza

Waaza is a production-ready WhatsApp REST API built with Go, powered by the whatsmeow library. It provides a complete backend for sending and receiving WhatsApp messages programmatically, with a built-in web dashboard for session management.

Designed for teams and businesses that need a reliable, self-hosted WhatsApp gateway without vendor lock-in.

• Multi-Instance Management — Run multiple WhatsApp sessions from a single server
• Role-Based Access Control — Admin and User roles with scoped permissions
• Async Message Queue — Durable outbox backed by PostgreSQL with exponential backoff retry
• Web Dashboard — Manage instances, scan QR codes, and monitor message status
• OpenAPI Specification — Full Swagger UI with documented endpoints
• Session Control — Connect, disconnect, logout, and QR pairing via Linked Devices
• Webhook Support — Configure callbacks for incoming messages
• Docker & Systemd Ready — Deploy anywhere with included configs
• CI/CD Pipeline — Automated Docker builds and release tagging via GitHub Actions

• Go 1.25+
• PostgreSQL 14+
• Git

git clone https://github.com/guna64/waaza.git
cd waaza

# Set environment variables
export PORT=8090
export WAAZA_PROVIDER=whatsmeow
export WAAZA_DB_DRIVER=pgx
export WAAZA_DB_DSN='postgres://waaza:password@127.0.0.1:5432/waaza?sslmode=disable'
export WAAZA_API_KEY='your-user-token'
export WAAZA_ADMIN_TOKEN='your-admin-token'

go run ./cmd/server

docker build -t waaza .
docker run -p 8090:8090 \
  -e WAAZA_DB_DSN='postgres://waaza:pass@host:5432/waaza?sslmode=disable' \
  -e WAAZA_API_KEY='your-user-token' \
  -e WAAZA_ADMIN_TOKEN='your-admin-token' \
  waaza

All API endpoints require an API key via the Authorization header.

Queue Status Flow: pending → processing → sent | failed → dead

sudo cp deploy/waaza.service /etc/systemd/system/
sudo mkdir -p /etc/waaza
sudo cp deploy/waaza.env.example /etc/waaza/waaza.env
sudo chmod 600 /etc/waaza/waaza.env

sudo systemctl daemon-reload
sudo systemctl enable --now waaza
sudo systemctl status waaza

waaza/
├── cmd/server/          # Application entrypoint
├── internal/
│   ├── api/             # HTTP handlers & routing
│   ├── config/          # Configuration management
│   ├── middleware/       # Auth middleware (API key)
│   ├── service/         # Business logic & outbox worker
│   ├── store/           # PostgreSQL persistence layer
│   └── wa/              # WhatsApp adapter (whatsmeow)
├── web/templates/       # Dashboard HTML templates
├── openapi/             # API specification
└── deploy/              # Systemd service & env template

Key Design Decisions:

• Hexagonal architecture — Clean separation between domain logic and adapters
• Outbox pattern — Reliable async message delivery with PostgreSQL-backed queue
• Port-based abstractions — WhatsApp adapter is swappable (mock adapter included for testing)

• Store credentials in /etc/waaza/waaza.env with 600 permissions
• Rotate WAAZA_ADMIN_TOKEN, WAAZA_API_KEY, and database passwords regularly
• Restrict network access (e.g., Tailscale/VPN only)
• Review logs before exposing publicly

• Contacts & groups management via whatsmeow
• Queue list/retry/cancel endpoints
• Token hashing & auth hardening
• Trusted proxies & security headers
• CI test pipeline

Contributions are welcome! Please open an issue or submit a pull request.

This project is licensed under the MIT License.