Integrazione WhatsApi

Panoramica

WhatsApi è un gateway WhatsApp self-hosted con accessi separati per cliente. Gli utenti possono registrarsi gratuitamente, confermare la propria email e collegare un’istanza. L'amministratore può anche creare gli account, gestire gli utenti e assegnare limiti. Ogni cliente dispone di istanze autorizzate e di una chiave API personale da utilizzare esclusivamente sul proprio backend.

Disconnessioni delle sessioni e possibili blocchi del numero

WhatsApi non è affiliato a Meta o WhatsApp e non utilizza l’API Cloud ufficiale. Il collegamento si basa su WhatsApp Web tramite la libreria Baileys. I rischi qui descritti possono verificarsi anche quando il server WhatsApi è funzionante.

1. Sessione scollegata

La sessione può interrompersi dopo aggiornamenti dell'app WhatsApp, disconnessioni dall'elenco Dispositivi collegati, problemi di autenticazione, variazioni di rete, logout o cambiamenti tecnici imposti da WhatsApp.

• Controlla lo stato dell'istanza nella dashboard: connected indica una sessione collegata; reconnecting, paused o logged_out indicano situazioni da verificare.
• Se necessario, riavvia l'istanza e scansiona un nuovo QR dall'app WhatsApp sul dispositivo principale.
• Finché l'istanza non torna connessa, l'invio e la ricezione automatizzata dei messaggi possono essere interrotti. Non viene garantita la consegna dei messaggi durante il disservizio.

2. Restrizioni, sospensione o blocco del numero

WhatsApp può imporre restrizioni alle funzionalità, sospendere l'account temporaneamente oppure bloccare il numero in modo permanente. Tra i fattori di rischio rientrano l'accesso tramite client non ufficiali, attività automatizzate non conformi, spam e segnalazioni degli altri utenti. Il rischio non è quantificabile né azzerabile.

WhatsApi non controlla tali decisioni e non può sbloccare un account. Se ricevi una notifica di blocco, segui la procedura di revisione dall'app WhatsApp, quando disponibile, e consulta la documentazione ufficiale. L'esito della revisione dipende esclusivamente da WhatsApp.

3. Misure prudenziali

• Collega soltanto numeri che possiedi o sei autorizzato a gestire.
• Evita messaggi automatici ripetitivi, campagne massive, spam e scraping.
• Rispetta consenso, norme applicabili e politiche WhatsApp.
• Monitora continuamente lo stato della sessione e prepara una modalità alternativa di contatto in caso di disconnessione o sospensione.
• Per processi critici, valuta la piattaforma ufficiale WhatsApp Business con i requisiti e le tariffe previsti.

Avvio rapido

1. Registrati gratuitamente con email e password (verifica email richiesta) oppure usa Google se abilitato. Gli utenti creati dall’amministratore possono usare le credenziali assegnate.
2. Accedi alla console WhatsApi, apri «API e sicurezza», genera la chiave API personale e conservala in un gestore di segreti.
3. Apri Le mie istanze, seleziona Crea istanza (se disponibile), poi Avvia.
4. Premi QR; sul telefono vai in WhatsApp → Dispositivi collegati → Collega un dispositivo e scansiona il codice.
5. Attendi lo stato connected e usa la chiave API dal server per richiamare gli endpoint.

curl -sS 'https://whatsapi.it/api/v1/instances' \
  -H 'Authorization: Bearer wa_LA_TUA_CHIAVE_API'

La chiave utilizzata nell'esempio è un segnaposto e deve essere sostituita con la credenziale personale.

Account e credenziali

L'utente può creare autonomamente un account gratuito dal sito, con verifica dell'email; l'amministratore può anche crearne uno in Gestione utenti. Per gli account creati dall'amministratore sono mostrate una sola volta la password temporanea e la chiave API. L'utente può modificare la password e rigenerare la chiave dalla console; l'amministratore può reimpostare le credenziali e modificare il limite delle istanze.

• La registrazione autonoma è gratuita e richiede verifica email e configurazione SMTP; l’accesso Google richiede le credenziali OAuth 2.0 configurate dall’amministratore.
• Ogni utente parte con un limite di 1 istanza, modificabile dall'amministratore.
• Disattivando un utente vengono bloccati il suo login e la sua API key. Questo non garantisce l'arresto automatico di eventuali sessioni WhatsApp già collegate: l'amministratore deve gestirle separatamente.
• La rigenerazione della API key rende immediatamente inutilizzabile la precedente.

Registrazione gratuita e Google OAuth

WhatsApi permette di registrarsi con email e password o, dopo l'attivazione da parte dell'amministratore, di continuare con Google. Il piano gratuito non richiede carta di credito e non ha una scadenza automatica. Ogni nuovo account inizia con un'istanza autorizzata.

Registrazione email

1. Apri WhatsApi e seleziona Registrati gratis.
2. Inserisci nome, indirizzo email e password di almeno 12 caratteri; leggi e accetta l'avvertenza sui rischi WhatsApp.
3. Apri il messaggio di verifica ricevuto via SMTP; il link scade dopo 24 ore. Puoi richiederne un nuovo invio dalla schermata di accesso.
4. Dopo la verifica, accedi e genera la chiave API personale in API e sicurezza.

La registrazione email è disponibile soltanto quando un amministratore ha configurato la posta SMTP in uscita. Per sicurezza, non vengono attivati account email privi di verifica.

Accedi o registrati con Google

L'amministratore apre Impostazioni → Google OAuth e inserisce Client ID e Client Secret creati su Google Cloud Console per un'applicazione web. L'URI di reindirizzamento autorizzato da configurare è:

Il flusso utilizza OAuth 2.0 / OpenID Connect con state, nonce, PKCE e verifica server-side del token ID firmato da Google. L'indirizzo email deve risultare verificato da Google. Per evitare acquisizioni non autorizzate, gli account email/password già presenti non vengono collegati automaticamente a un'altra identità Google soltanto perché l'email coincide.

Importante: le credenziali Google sono necessarie per rendere operativo il pulsante «Continua con Google». Il sistema di abbonamenti a pagamento rimane disabilitato.

Autenticazione API

Per tutte le chiamate a /api/v1/ usa una chiave personale nell'header Authorization. La chiave ha forma wa_ seguita da 64 caratteri esadecimali.

Authorization: Bearer wa_LA_TUA_CHIAVE_API
Accept: application/json

Le API REST pubbliche sono pensate per l'utilizzo server-to-server. Non inserire mai la chiave in JavaScript eseguito nel browser, in un'app mobile distribuita, in un repository o in un URL. Le chiamate dal pannello web utilizzano invece cookie di sessione e protezione CSRF.

URL e convenzioni

Le API restituiscono JSON; usa Content-Type: application/json per le richieste con un corpo. I numeri destinatari devono avere soltanto cifre, comprensive di prefisso internazionale e senza segno + (esempio italiano: 393XXXXXXXXX).

L'identificativo dell'istanza è creato dal portale e ha formato simile a wa_a1b2c3d4e5f6.... Per chiamare le API usa l'ID esatto visualizzato nella console, non un numero di telefono.

Restituisce soltanto le istanze appartenenti al proprietario della chiave API, con il limite configurato dall'amministratore.

curl 'https://whatsapi.it/api/v1/instances' \
  -H 'Authorization: Bearer wa_LA_TUA_CHIAVE_API'

{
  "instances": [
    {
      "id": "wa_0123456789abcdef01234567",
      "status": "connected",
      "hasQr": false,
      "phone": "393XXXXXXXXX:1@s.whatsapp.net",
      "updatedAt": "2026-11-06T12:00:00.000Z"
    }
  ],
  "max": 1
}

Le date sono in formato UTC ISO 8601. La proprietà phone può essere null prima della connessione.

Restituisce stato, presenza del QR, telefono eventualmente associato e data dell'ultimo aggiornamento.

curl 'https://whatsapi.it/api/v1/instances/wa_0123456789abcdef01234567' \
  -H 'Authorization: Bearer wa_LA_TUA_CHIAVE_API'

Stati possibili includono not_started, connecting, qr_ready, connected, reconnecting, paused e logged_out. Alcuni stati sono transitori.

Avvia l'istanza esistente e avvia la negoziazione con WhatsApp. L'operazione può richiedere qualche istante. Dopo l'avvio consulta lo stato e, se necessario, il QR.

curl -X POST 'https://whatsapi.it/api/v1/instances/wa_0123456789abcdef01234567/start' \
  -H 'Authorization: Bearer wa_LA_TUA_CHIAVE_API'

Risposta attesa: 202 Accepted se la richiesta è accettata. Non equivale a una connessione già completata.

Disponibile quando lo stato è qr_ready. Restituisce qrDataUrl, una stringa immagine PNG in formato data:image/png;base64,....

curl 'https://whatsapi.it/api/v1/instances/wa_0123456789abcdef01234567/qr' \
  -H 'Authorization: Bearer wa_LA_TUA_CHIAVE_API'

{
  "id": "wa_0123456789abcdef01234567",
  "qrDataUrl": "data:image/png;base64,iVBORw0KGgo...",
  "updatedAt": "2026-11-06T12:00:00.000Z"
}

Come collegare: apri WhatsApp sul telefono, seleziona Dispositivi collegati, poi Collega un dispositivo e scansiona il codice. I QR scadono; se non è disponibile, attendi oppure riavvia la connessione e riprova. Se l'istanza è già associata, il gateway può rispondere con 404 perché non esiste un QR pendente.

Sicurezza: un QR è una credenziale di associazione temporanea. Non registrarlo in log, non inviarlo a terzi e non renderlo pubblico.

Ferma il collegamento mantenendo le credenziali WhatsApp salvate. Potrai riavviarlo in seguito; non equivale a effettuare il logout sul dispositivo o a cancellare definitivamente l'istanza.

curl -X POST 'https://whatsapi.it/api/v1/instances/wa_0123456789abcdef01234567/pause' \
  -H 'Authorization: Bearer wa_LA_TUA_CHIAVE_API'

Consente l'invio di solo testo, da un'istanza già collegata. Il numero va scritto con prefisso internazionale senza +. La richiesta accettata restituisce HTTP 202: non significa che il destinatario abbia già ricevuto o letto il messaggio.

curl -X POST 'https://whatsapi.it/api/v1/instances/wa_0123456789abcdef01234567/messages' \
  -H 'Authorization: Bearer wa_LA_TUA_CHIAVE_API' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: richiesta-ordine-10021' \
  -d '{
    "to": "393XXXXXXXXX",
    "text": "Ciao! Questo è un messaggio di prova."
  }'

{
  "id": "identificativo-messaggio",
  "sessionId": "wa_0123456789abcdef01234567",
  "status": "accepted"
}

Idempotenza

Genera una chiave univoca per ogni invio logico. Se il client ritenta la stessa operazione a seguito di un errore di rete, riutilizza la medesima Idempotency-Key, evitando possibili messaggi duplicati. Non riutilizzare la stessa chiave per messaggi diversi. In caso di 409, non ripetere automaticamente con una nuova chiave senza verificare lo stato.

Legge l'archivio degli eventi di messaggio ricevuti e associati all'account. limit va da 1 a 100; valore predefinito: 50.

curl 'https://whatsapi.it/api/v1/events?limit=20' \
  -H 'Authorization: Bearer wa_LA_TUA_CHIAVE_API'

{
  "events": [
    {
      "id": "f8d7c7a0-1234-4c00-8a11-123456789012",
      "sessionId": "wa_0123456789abcdef01234567",
      "occurredAt": "2026-11-06T12:05:00.000Z",
      "type": "text",
      "from": "393XXXXXXXXX@s.whatsapp.net",
      "text": "Buongiorno",
      "messageId": "ABC123",
      "hasMedia": false
    }
  ]
}

La conservazione locale degli eventi è limitata a massimo 500 messaggi per account e 7 giorni; non è uno storico permanente. La gestione dei messaggi multimediali per gli account pubblici espone soltanto hasMedia, non un endpoint di download. Al momento non è disponibile un webhook cliente configurabile dalla console: per leggere le conversazioni si può interrogare l'endpoint eventi con un polling ragionevole.

Restituisce nome, email, stato, limite di istanze e ID assegnati. Non restituisce password o API key.

curl 'https://whatsapi.it/api/v1/me' \
  -H 'Authorization: Bearer wa_LA_TUA_CHIAVE_API'

Integrazione Node.js

Esempio di chiamata dal backend Node.js 18+ con fetch. Conserva la chiave come variabile d'ambiente.

const API_URL = 'https://whatsapi.it/api/v1';
const key = process.env.WHATSAPI_API_KEY;
const instanceId = process.env.WHATSAPI_INSTANCE_ID;

async function inviaMessaggio(to, text, requestId) {
  const response = await fetch(
    `${API_URL}/instances/${instanceId}/messages`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${key}`,
        'Content-Type': 'application/json',
        'Idempotency-Key': requestId
      },
      body: JSON.stringify({ to, text })
    }
  );

  const body = await response.json();
  if (!response.ok) {
    throw new Error(`WhatsApi HTTP ${response.status}: ${body.error}`);
  }
  return body; // status: accepted, non consegnato
}

// Usa un ID stabile per ogni messaggio da inviare.
// Esegui solo sul backend, non nel browser.

Integrazione Python

Esempio con requests installabile tramite pip install requests.

import os
import requests

base = "https://whatsapi.it/api/v1"
headers = {
    "Authorization": f"Bearer {os.environ['WHATSAPI_API_KEY']}"
}

response = requests.get(
    f"{base}/instances",
    headers=headers,
    timeout=15
)
response.raise_for_status()

for instance in response.json()["instances"]:
    print(instance["id"], instance["status"])

Codici HTTP e risoluzione problemi

Il QR non compare

Avvia l'istanza; attendi alcuni secondi; controlla che sia nello stato qr_ready. Se è già connected, non serve un nuovo QR.

I messaggi non partono

Verifica che la sessione sia connected, che la funzione di invio del gateway sia abilitata, che il numero contenga il prefisso internazionale senza + e che l'API key sia valida.

Impossibile raggiungere il dominio

Controlla DNS, certificato HTTPS e connessione del gateway. Durante l'attivazione del dominio può essere necessario utilizzare temporaneamente l'indirizzo tecnico già disponibile.

Sicurezza, dati e uso responsabile

• Usa soltanto HTTPS e conserva le credenziali in un secret manager o variabili d'ambiente protette.
• Non incorporare le chiavi in siti web, app mobile, screenshot, log o repository.
• Rigenera la chiave API se sospetti una compromissione; aggiorna subito tutte le integrazioni che la usano.
• Associa soltanto numeri e account che controlli e invia comunicazioni a destinatari che hanno fornito il consenso necessario.
• Applica la normativa privacy, le regole di WhatsApp e le politiche antispam; fornisci un canale di disiscrizione per le comunicazioni promozionali.
• La piattaforma si basa su un'automazione non ufficiale di WhatsApp Web: possono esserci interruzioni, restrizioni o cambi di compatibilità imposti dal servizio di terze parti.
• Il recupero degli eventi è limitato: mantieni uno storico nel tuo sistema se necessario e definisci basi giuridiche, tempi di conservazione e sicurezza dei dati.

Funzionalità disponibili e limiti attuali

Questa documentazione riguarda le API cliente di WhatsApi, non i servizi riservati al motore interno o alle integrazioni HelloGuest.

Riferimento Baileys: cosa supporta WhatsApi?

Il gateway impiega la libreria @whiskeysockets/baileys 7.0.0-rc14 (WhatsApp Web, non API Cloud ufficiali). La tabella riporta il livello reale di accessibilità: «API pubblica» significa disponibile oggi sotto https://whatsapi.it/api/v1; «Motore interno» significa presente nel backend gateway, ma non accessibile dai token degli utenti; «Libreria / roadmap» significa previsto o potenzialmente realizzabile mediante ulteriore sviluppo e collaudi.

Immagini, video, PDF e allegati

La libreria Baileys espone oggetti image, video, document e sticker. Il motore interno di WhatsApi gestisce già image, video, document, con file Base64 e un limite di 12 MiB per invio. I payload della seguente sezione descrivono il contratto tecnico interno, non chiamate pubbliche già utilizzabili.

{
  "to": "393XXXXXXXXX",
  "type": "image",
  "mediaBase64": "<BASE64_DELL_IMMAGINE>",
  "mimetype": "image/jpeg",
  "caption": "La nostra nuova collezione"
}

{
  "to": "393XXXXXXXXX",
  "type": "document",
  "mediaBase64": "<BASE64_DEL_PDF>",
  "mimetype": "application/pdf",
  "filename": "preventivo.pdf"
}

In Baileys puoi passare Buffer, {url} o {stream} a sendMessage. Per file di grandi dimensioni la libreria consiglia lo streaming. Nella nostra implementazione attuale, invece, il motore usa un Buffer da Base64: pubblicare upload tramite URL richiede convalida e protezioni SSRF.

await sock.sendMessage(jid, {
  image: { url: './foto.jpg' },
  caption: 'Foto del prodotto'
});

await sock.sendMessage(jid, {
  document: { url: './preventivo.pdf' },
  mimetype: 'application/pdf',
  fileName: 'preventivo.pdf'
});

await sock.sendMessage(jid, {
  video: { url: './demo.mp4' },
  caption: 'Dimostrazione del servizio'
});

Altri tipi di media

Baileys prevede sticker, GIF riprodotte come video MP4 con gifPlayback: true, video circolari con ptv: true e contenuti viewOnce. Sono opzioni da implementare e testare nelle API pubbliche, valutando anche la compatibilità tra versioni di WhatsApp.

Media in entrata

Il gateway può acquisire immagini, audio, video, documenti e sticker usando downloadMediaMessage. L'archivio cliente oggi rende disponibile solo il tipo e hasMedia; non espone il file binario al cliente. Una futura API dovrà implementare controllo di appartenenza dell'istanza, verifica del tipo MIME, antivirus ove necessario e scadenza del download.

Audio, note vocali e conversioni

Nel motore interno di WhatsApi il tipo audio accetta mediaBase64, mimetype e il flag booleano ptt: true richiede l'invio come nota vocale, false come allegato audio. Non è ancora esposto tramite /api/v1.

{
  "to": "393XXXXXXXXX",
  "type": "audio",
  "mediaBase64": "<BASE64_FILE_AUDIO>",
  "mimetype": "audio/ogg; codecs=opus",
  "ptt": true
}

La documentazione Baileys raccomanda una codifica Opus, preferibilmente in OGG e mono, per ottenere note vocali riproducibili su molti dispositivi. Un comando di preparazione può essere:

ffmpeg -i input.mp3 -c:a libopus -b:a 32k -ac 1 output.ogg

await sock.sendMessage(jid, {
  audio: { url: './output.ogg' },
  mimetype: 'audio/ogg; codecs=opus',
  ptt: true
});

Formati, durate massime, trascrizione vocale e sintesi TTS sono capacità applicative separate da Baileys; non sono incluse automaticamente nel gateway WhatsApi.

Stati dei messaggi e conferme di lettura

È fondamentale distinguere lo stato della richiesta HTTP dallo stato WhatsApp del messaggio. L'attuale risposta 202 {status: "accepted"} indica che il gateway ha accettato l'invio; non è una ricevuta di consegna o lettura.

Le conferme di lettura possono mancare per impostazioni privacy o tipo di chat; l'assenza non dimostra la mancata lettura. Le ricevute di gruppo richiedono la gestione per partecipante. Per rendere affidabili questi stati serviranno un archivio messaggi per sessionId + messageId, ascolto degli eventi Baileys, normalizzazione delle transizioni e API cliente dedicate.

sock.ev.on('messages.update', updates => {
  for (const { key, update } of updates) {
    // correla key.id, key.remoteJid e sessionId
    // conserva update.status e aggiorna la cronologia
  }
});
sock.ev.on('message-receipt.update', receipts => {
  for (const { key, receipt } of receipts) {
    // aggiorna ricevute per utente/partecipante
  }
});

Eventi, reazioni e presenza

Il repository GitHub di Baileys definisce eventi messages.upsert, messages.update, messages.delete, messages.reaction, message-receipt.update, presence.update, contacts.upsert, chats.update, call e numerosi eventi di gruppi. WhatsApi attualmente raccoglie gli arrivi con messages.upsert e inoltra gli eventi delle nuove conversazioni al proprio archivio cliente.

Reazioni emoji

await sock.sendMessage(jid, {
  react: {
    text: '👍',
    key: originalMessage.key
  }
});
// text: '' può rimuovere la reazione

Stato «sta scrivendo», online e lettura

await sock.sendPresenceUpdate('composing', jid);
await sock.sendPresenceUpdate('paused', jid);
await sock.readMessages([message.key]);

Le indicazioni di presenza sono temporanee. La lettura richiede le chiavi dei singoli messaggi e una mappatura JID accurata (compresi i casi in cui WhatsApp restituisce LID invece del numero). Per il supporto a reazioni, modifiche, inoltri, citazioni ed eliminazioni bisogna salvare WAMessageKey e rispettare le autorizzazioni per la sessione proprietaria.

Messaggi modificati, eliminati e citati

La libreria supporta le operazioni edit, delete e l'opzione quoted, ma il prodotto WhatsApi non ha ancora API cliente per queste operazioni. Richiedono persistenza del messaggio originale e verifica dei vincoli WhatsApp.

Storie (Stati), broadcast, gruppi, contatti e sondaggi

Qui «Stati WhatsApp» indica le Storie pubblicate in WhatsApp, da non confondere con gli stati di consegna dei messaggi descritti sopra.

Prima di abilitare invii a gruppi, broadcast o Stati serviranno limiti di utilizzo, consenso, tracciamento, sicurezza multi-tenant e verifica di compatibilità con la release di Baileys utilizzata.

Contratti API proposti (non ancora utilizzabili)

La sintassi seguente descrive una proposta architetturale per l'estensione delle API pubbliche. Non è una specifica OpenAPI attiva e le richieste restituirebbero 404 finché il backend non viene implementato.

Proposta di schema media per API pubblica futura

{
  "type": "audio",
  "to": "393XXXXXXXXX",
  "mediaBase64": "BASE64...",
  "mimetype": "audio/ogg; codecs=opus",
  "ptt": true,
  "caption": null
}

Un'estensione produzione dovrebbe preferire upload temporanei protetti o streaming, dimensioni massime esplicite, scansioni, scadenza media, rate limiting, audit, limiti per utente, monitoraggio dei costi e risposte uniformi.

Documentazione e sorgenti GitHub

Questa sezione avanzata è stata elaborata consultando il codice del gateway installato e la documentazione pubblica del progetto WhiskeySockets/Baileys, non un repository Git del portale WhatsApi (che attualmente non è configurato sul VPS).

• GitHub · WhiskeySockets/Baileys — repository di riferimento
• README ufficiale — invio messaggi, media, presenza, chat, gruppi e broadcast
• Message.ts — tipi e payload dei messaggi
• Events.ts — eventi e ricevute
• Receiving Updates — semantica dei principali eventi
• Media Messages — audio, video, immagini, documenti e sticker

Le funzionalità di Baileys e di WhatsApp possono cambiare nel tempo. Gli esempi «libreria» sono illustrativi e devono essere compatibili con la versione 7.0.0-rc14 attualmente impiegata prima di essere portati nel prodotto.

Glossario

Istanza

Collegamento logico tra WhatsApi e un account WhatsApp.

API key

Credenziale segreta che autentica il backend del cliente.

QR Code

Codice temporaneo per associare il dispositivo WhatsApp.

Idempotency-Key

Identificativo stabile della richiesta di invio per ridurre i duplicati.

202 Accepted

Richiesta ricevuta e accettata, non prova di recapito del messaggio.

Polling

Controllo periodico tramite API per verificare eventi o stati.