Gestisci le tue sessioni WhatsApp
Monitoraggio invio messaggi in tempo reale
Benvenuto nell'API della Piattaforma WhatsApp. Usa questi endpoint per integrare l'invio di messaggi nelle tue applicazioni.
Tutte le chiamate API sono protette e richiedono un'autenticazione tramite API Key.
Effettua una richiesta POST per ottenere il tuo token di accesso:
POST /auth/login
{
"username": "admin",
"password": "password123"
}
// Risposta:
{ "token": "a1b2c3d4..." }
Includi la chiave nell'header x-api-key di ogni richiesta successiva:
x-api-key: a1b2c3d4...
Nuovi endpoint per monitorare lo stato del server e delle sessioni.
Controlla se il server è attivo. Non richiede autenticazione:
GET /health
// Risposta:
{
"status": "ok",
"pid": 12345,
"uptime": 3600.5
}
Ottieni versione della libreria e numero di sessioni attive:
GET /system/info
// Risposta:
{
"pid": 12345,
"installed": "1.34.4",
"latest": "1.34.4",
"updateAvailable": false,
"sessions": 2
}
Le sessioni di WhatsApp sono gestite tramite clientId (una stringa univoca definita da te).
Una sessione può trovarsi in uno dei seguenti stati:
| Stato | Descrizione |
|---|---|
INITIALIZING |
Sessione in fase di avvio |
QR_READY |
QR code pronto per la scansione |
AUTHENTICATED |
QR scansionato, sincronizzazione in corso |
READY |
✅ Pronto per inviare/ricevere messaggi |
DISCONNECTED |
Disconnesso, riconnessione automatica in corso |
RECONNECTING |
Tentativo di riconnessione |
AUTH_FAILURE |
❌ Autenticazione fallita |
POST /sessions
{ "clientId": "il-tuo-id" }
GET /sessions
// Risposta:
[
{ "id": "session-1", "status": "READY", "lastError": null },
{ "id": "session-2", "status": "QR_READY", "lastError": null }
]
GET /sessions/:clientId/status
// Risposta:
{ "status": "READY", "lastError": null }
GET /sessions/:clientId/qr
// Risposta (se disponibile):
{ "qr": "data:image/png;base64,...", "raw": "..." }
DELETE /sessions/:clientId
I messaggi vengono accodati e inviati con ritardi casuali per simulare un comportamento umano.
🔒 Comportamento Coda:
Esempio: Un messaggio di 50 caratteri richiederà ~15-25 secondi
POST /sessions/:clientId/message
{
"number": "39333123456",
"message": "Ciao Mondo"
}
// Risposta:
{
"queued": true,
"position": 5,
"estimatedDelay": "15-55 seconds"
}
Per inviare immediatamente (senza coda), aggiungi "immediate": true:
{
"number": "39333123456",
"message": "Urgente!",
"immediate": true
}
GET /sessions/:clientId/queue
// Risposta:
{
"pending": 5,
"processing": true,
"queueSize": 6
}
Per ricevere i messaggi in tempo reale, configura la variabile d'ambiente WEBHOOK_URL nel
file
.env.
Il sistema invierà una richiesta POST automatica a quell'URL per ogni nuovo messaggio.
Esempio di Payload JSON inviato:
{
"sessionId": "session-1",
"from": "39333123456@c.us",
"to": "39333987654@c.us",
"body": "Ciao!",
"context": "Privato",
"timestamp": 1704283400,
"hasMedia": false,
"type": "chat"
}
Nota: Non sono presenti firme di sicurezza o criptografia nell'header. Assicurati che l'URL del tuo Webhook sia segreto o gestisca la convalida internamente.
Se non puoi usare i Webhook, puoi interrogare periodicamente questo endpoint:
GET /sessions/:clientId/messages
Puoi filtrare quali tipi di messaggi vengono salvati nei log e inviati al webhook. I tipi disponibili sono:
| Tipo | Descrizione |
|---|---|
Privato |
Messaggi uno-a-uno diretti |
Gruppo |
Messaggi nei gruppi |
Stato |
Storie/Status dei contatti |
Broadcast |
Liste broadcast |
GET /sessions/:clientId/filters
// Risposta:
{ "filters": ["Privato", "Gruppo"] }
PUT /sessions/:clientId/filters
{
"filters": ["Privato"] // Solo messaggi privati
}
// Risposta:
{ "success": true, "filters": ["Privato"] }
Nota: Se l'array è vuoto [], tutti i messaggi passano (nessun filtro attivo).
Variabili d'ambiente disponibili:
# Porta del server (default: 3000) PORT=3000 # Credenziali admin ADMIN_USERNAME=admin ADMIN_PASSWORD=password123 # API Key fissa (opzionale, altrimenti generata automaticamente) WA_API_KEY=your_secret_key # URL per ricevere messaggi in tempo reale WEBHOOK_URL=https://tuo-server.com/webhook
Se vedi l'errore "Another instance is already running", elimina il file .server.pid:
rm .server.pid
Controlla che non ci siano processi Chrome orfani:
pkill -9 -f ".wwebjs_auth"
curl http://localhost:3000/health
Inserisci un ID univoco per questa sessione.
Seleziona quali tipi di messaggi ricevere. Se nessuno è selezionato, tutti i messaggi passano.
Ricevi i messaggi in tempo reale sul tuo server.
Inserisci Username e Password.