OpenWA

Introduzione

OpenWA è un gateway API WhatsApp open source, gratuito e self-hosted pensato per sviluppatori che vogliono avere pieno controllo sulla propria infrastruttura di messaggistica, evitando blocchi da vendor e costi nascosti.

Costruito con un'architettura modulare, OpenWA permette di cambiare database (SQLite/PostgreSQL), storage (locale/S3) e cache (Memory/Redis) senza modificare una riga di codice.

Caratteristiche

Funzionalità core

Messaggistica

Funzionalità avanzate

Infrastruttura

Installazione

Opzione A: Docker (consigliato)

git clone https://github.com/rmyndharis/OpenWA.git
cd OpenWA
docker compose -f docker-compose.dev.yml up -d

Accesso:

• Dashboard: http://localhost:2886
• API: http://localhost:2785/api
• Swagger: http://localhost:2785/api/docs

Opzione B: Sviluppo locale

git clone https://github.com/rmyndharis/OpenWA.git
cd OpenWA
npm install
npm run dev

Accesso come sopra.

Deploy in produzione

Utilizza docker-compose.yml con profili opzionali:

docker compose up -d                    # Base: SQLite, storage locale

docker compose --profile postgres up -d  # Postgres DB

docker compose --profile full up -d       # Stack completo (Postgres, Redis, Dashboard, Traefik)

Porte utilizzate

Esempi di API

• Creazione sessione:

curl -X POST http://localhost:2785/api/sessions \
 -H "Content-Type: application/json" \
 -H "X-API-Key: YOUR_API_KEY" \
 -d '{"name": "my-bot"}'

• Avvio sessione e QR Code:

curl -X POST http://localhost:2785/api/sessions/{sessionId}/start \
 -H "X-API-Key: YOUR_API_KEY"
curl http://localhost:2785/api/sessions/{sessionId}/qr \
 -H "X-API-Key: YOUR_API_KEY"

• Invia messaggio:

curl -X POST http://localhost:2785/api/sessions/{sessionId}/messages/send-text \
 -H "Content-Type: application/json" \
 -H "X-API-Key: YOUR_API_KEY" \
 -d '{"chatId": "628123456789@c.us", "text": "Hello from OpenWA!"}'

• Configura webhook:

curl -X POST http://localhost:2785/api/sessions/{sessionId}/webhooks \
 -H "Content-Type: application/json" \
 -H "X-API-Key: YOUR_API_KEY" \
 -d '{"url": "https://your-server.com/webhook", "events": ["message.received", "session.status"], "secret": "your-hmac-secret"}'

Tech Stack

Struttura progetto

openwa/
├── src/                 # Codice sorgente
│   ├── main.ts          # Entry point
│   ├── app.module.ts    # Modulo root
│   ├── config/          # Configurazioni
│   ├── common/          # Utilità comuni
│   │   ├── cache/       # Cache Redis
│   │   └── storage/     # Storage file
│   ├── core/            # Core system
│   │   ├── hooks/       # Plugin hooks
│   │   └── plugins/     # Sistema plugin
│   ├── engine/          # Astrazione WhatsApp
│   └── modules/         # Moduli funzionali
│       ├── session/
│       ├── message/
│       ├── webhook/
│       ├── group/
│       ├── contact/
│       ├── auth/
│       ├── infra/
│       └── health/
├── dashboard/           # Dashboard React
├── docs/                # Documentazione
├── docker-compose.yml
├── Dockerfile
└── package.json

Documentazione

Documenti dettagliati sono disponibili in docs/:

Contribuire

Per contribuire:

1. Fai fork del progetto
2. Crea un branch feature (git checkout -b feature/nome-feature)
3. Fai commit delle modifiche
4. Push sul branch
5. Apri una Pull Request

Leggi le Development Guidelines per standard di codice.

Licenza

OpenWA è rilasciato sotto licenza MIT, gratuito per usi personali e commerciali.

Vedi il file LICENSE per i dettagli.