Come inviare messaggi WhatsApp con un’API non ufficiale e n8n: la guida completa

Se vuoi inviare e ricevere messaggi WhatsApp da un’automazione come n8n ma non puoi (o non vuoi) usare l’API ufficiale di WhatsApp Business, ti imbatterai presto nelle API WhatsApp «non ufficiali». Sono gateway che si collegano a WhatsApp nello stesso modo di WhatsApp Web ed espongono una semplice API HTTP richiamabile da n8n. Questa guida copre le otto opzioni più popolari da cima a fondo: cos’è ciascuna, come configurarla, l’endpoint e il payload esatti per inviare un messaggio, un confronto fianco a fianco, e, soprattutto, i compromessi da capire prima di costruire qualsiasi cosa.

Cosa significa davvero «non ufficiale»

L’accesso ufficiale a WhatsApp per le aziende passa dall’API WhatsApp Business di Meta (la Cloud API), che richiede la verifica dell’azienda, usa modelli di messaggio pre-approvati e fattura per conversazione. Le API non ufficiali saltano tutto questo: eseguono una sessione di WhatsApp Web per un numero normale (molte si basano sulla libreria open-source Baileys o su un browser headless) e la avvolgono in un’API REST.

Quella comodità arriva con una vera avvertenza. Automatizzare così un numero personale non è sanzionato da Meta e può violare i Termini di servizio di WhatsApp. I numeri possono essere limitati o bannati, il più delle volte quando vengono usati per inviare messaggi di massa non richiesti a persone che non hanno mai dato il consenso. Considera le API non ufficiali ideali per progetti personali, strumenti interni, notifiche e chat bidirezionale con persone che si aspettano di sentirti. Per un contatto conforme e su larga scala, l’API ufficiale tramite un fornitore come Wati è la strada giusta. E se sei idoneo all’API ufficiale ma preferisci non self-hostare nulla, strumenti interamente ospitati come Zapier o Make collegano WhatsApp tramite la Cloud API ufficiale senza alcun server da gestire. Vedi la nostra guida all’automazione per il quadro completo.

La ricetta che ogni gateway segue

Una volta vista una di queste API, le hai viste essenzialmente tutte. Le differenze stanno in hosting, prezzi e dettagli del payload, il flusso è identico:

1. Collega un numero. Crei un’«istanza», «sessione» o «canale» per un numero WhatsApp dedicato e scansioni un codice QR da WhatsApp → Dispositivi collegati, esattamente come se accedessi a WhatsApp Web.
2. Ottieni una credenziale. Il fornitore ti dà una chiave API o un token che autentica ogni richiesta.
3. Invia via HTTP. In n8n, un nodo HTTP Request fa POST all’endpoint di invio del fornitore con destinatario e testo. (Evolution API e Wassenger offrono anche nodi n8n dedicati se preferisci non costruire le richieste a mano.)
4. Ricevi via webhook. Punti il webhook del fornitore a un nodo Webhook di n8n, così ogni messaggio in arrivo avvia un workflow, la base di autoresponder e chatbot.

I numeri dei destinatari sono sempre in formato internazionale completo, solo cifre, lo stesso formato di un link click-to-chat. Alcuni fornitori avvolgono il numero in un chat ID come 15551234567@c.us (individuale) o @g.us (gruppo); le sezioni per fornitore qui sotto indicano quali.

Gateway self-hosted: Evolution API, WAHA, WPPConnect

I gateway self-hosted girano sul tuo server (con Docker è questione di un comando su qualsiasi VPS economico). Non paghi nulla per messaggio né abbonamenti (solo il tuo server) e i dati dei tuoi messaggi non passano mai da terzi, il che conta se gestisci liste di contatti sensibili. Il prezzo è che li operi tu: aggiornamenti, backup e qualche nuova scansione quando una sessione cade.

Evolution API, il più grande ecosistema n8n

Evolution API è un gateway gratuito e open-source, la scelta più popolare tra i team tecnici. Avvolge Baileys per il protocollo di WhatsApp Web (e può anche fare da facciata alla Cloud API ufficiale), supporta più istanze (ciascuna legata a un numero) e ha sia un nodo community dedicato (n8n-nodes-evolution-api) sia un grande ecosistema di template n8n pronti.

Configurazione: avvia il container Docker con una chiave API globale (per esempio la variabile d’ambiente AUTHENTICATION_API_KEY, il docker-compose del progetto mostra i nomi attuali), crea un’istanza via API o dall’interfaccia del manager, poi richiedi il codice QR dell’istanza e scansionalo. La documentazione Swagger è servita sulla stessa porta per esplorare gli endpoint.

• Endpoint di invio: POST https://tuo-server/message/sendText/tua-istanza
• Autenticazione: apikey: la-tua-chiave-api (header)
• Body (JSON): { "number": "15551234567", "text": "Ciao da n8n + Evolution API" }

WAHA, un container, più engine, ottimo con i media

WAHA (WhatsApp HTTP API) gira come singola immagine Docker e organizza le connessioni in sessioni (quella predefinita si chiama letteralmente “default”). Il suo tratto distintivo è la scelta degli engine, un engine WEBJS basato su browser ed engine NOWEB/GOWS più leggeri basati su websocket, per bilanciare consumo di risorse e funzionalità. Il core è gratuito da self-hostare; il WAHA Plus a pagamento sblocca capacità avanzate. È particolarmente solido con i media (immagini, file, note vocali), il che si adatta a chatbot più ricchi.

Configurazione: esegui l’immagine (API sulla porta 3000 di default, con documentazione Swagger interattiva), avvia una sessione, recupera il suo codice QR e scansionalo. Quando lo stato della sessione è “working”, puoi inviare. Se proteggi l’istanza con una chiave API, passala nell’header che WAHA si aspetta (per esempio X-Api-Key).

• Endpoint di invio: POST http://tuo-host-waha:3000/api/sendText
• Body (JSON): { "session": "default", "chatId": "[email protected]", "text": "Ciao da n8n + WAHA" }
• Nota: il suffisso del chatId è @c.us per gli individui, @g.us per i gruppi.

WPPConnect, open-source con token per sessione

WPPConnect Server è il fratello community degli altri due: gratuito, open-source e self-hosted, di solito sulla porta 21465 con documentazione Swagger. Il suo modello di autenticazione è leggermente diverso: imposti una SECRET_KEY sul server, chiami l’endpoint di generazione token per coniare un token Bearer per una sessione con nome, avvii la sessione e scansioni il suo QR. Espone endpoint per media, file, pulsanti e gruppi oltre al testo semplice.

• Endpoint di invio: POST http://tuo-server:21465/api/tua-sessione/send-message
• Autenticazione: Authorization: Bearer il-tuo-token-di-sessione
• Body (JSON): { "phone": "14155550100", "message": "Ciao da n8n + WPPConnect" }

Gateway cloud: Green API, UltraMsg, Wassenger, Whapi.cloud, Maytapi

I gateway cloud ospitano tutto per te: ti registri, colleghi un numero via QR e inizi a chiamare un’API, spesso in dieci minuti, senza nulla da mantenere. In cambio paghi un abbonamento e il tuo traffico passa dai server del fornitore. Tutti e cinque qui sotto seguono lo stesso schema e differiscono soprattutto per prezzo, rifinitura e una o due funzioni di punta.

Green API, la partenza più rapida, livello gratuito per sviluppatori

Green API dà a ogni istanza due valori (un idInstance e un apiTokenInstance) incorporati direttamente nell’URL della richiesta, quindi non ci sono header da configurare. Ha un livello gratuito per i test, documentazione chiara e consente messaggi di testo molto lunghi. I messaggi in arrivo arrivano via webhook o interrogando la coda di notifiche con ReceiveNotification; con n8n i webhook sono la scelta più pulita.

• Endpoint di invio: POST https://api.green-api.com/waInstance{idInstance}/sendMessage/{apiTokenInstance}
• Body (JSON): { "chatId": "[email protected]", "message": "Ciao da n8n + Green API" }

UltraMsg, l’opzione più semplice ed economica

UltraMsg è il minimalista del gruppo: ottieni un ID istanza (tipo instance12345) e un token, e invii messaggi con una singola richiesta form-encoded, niente JSON, niente nodo speciale. Una risposta corretta somiglia a { "sent": "true", "message": "ok", "id": 497 }. È una scelta pragmatica per notifiche semplici e piccoli chatbot dove costo e tempo di configurazione contano di più.

• Endpoint di invio: POST https://api.ultramsg.com/instance12345/messages/chat
• Body (Form-Urlencoded): token = il-tuo-token, to = 15551234567, body = Ciao da n8n + UltraMsg

Wassenger, funzioni business e nodo nativo n8n

Wassenger punta agli utenti business: aggiunge una casella condivisa per il team sopra l’API e, cosa notevole, offre un’integrazione nativa con n8n, così puoi usare un nodo Wassenger invece di configurare richieste HTTP. Colleghi un dispositivo via QR, crei una chiave API e la passi in un header Token. Oltre al testo può inviare media, documenti, posizioni, sondaggi e pulsanti, e scrivere ai gruppi.

• Endpoint di invio: POST https://api.wassenger.com/v1/messages
• Autenticazione: Token: la-tua-chiave-api (header)
• Body (JSON): { "phone": "+14155550100", "message": "Ciao da n8n + Wassenger" }

Whapi.cloud, REST pulito con token per canale

Whapi.cloud tratta ogni numero collegato come un «canale» con il proprio token Bearer, un modello ordinato se gestisci più numeri per scopi diversi. Gli endpoint REST sono puliti e ben documentati, c’è un livello gratuito per i prototipi, e il campo to accetta ID di gruppi e canali oltre ai numeri individuali (solo cifre, senza segno più).

• Endpoint di invio: POST https://gate.whapi.cloud/messages/text
• Autenticazione: Authorization: Bearer il-tuo-token-di-canale
• Body (JSON): { "to": "14155550100", "body": "Ciao da n8n + Whapi.cloud" }

Maytapi, costruita per gestire più numeri

Il punto di forza di Maytapi è il supporto multi-telefono: un account (un «prodotto») può contenere più istanze telefoniche, ciascuna indirizzata dal proprio phone ID nell’URL. Ti autentichi con un token nell’header x-maytapi-key, e lo stesso endpoint invia media, posizioni e contatti cambiando il campo type. I webhook si configurano una volta per prodotto.

• Endpoint di invio: POST https://api.maytapi.com/api/tuo-product-id/tuo-phone-id/sendMessage
• Autenticazione: x-maytapi-key: il-tuo-token (header)
• Body (JSON): { "to_number": "14155550100", "type": "text", "message": "Ciao da n8n + Maytapi" }

Tabella comparativa

Tutte e otto fianco a fianco. «Self-hosted» significa che la esegui tu (tipicamente con Docker) e paghi solo il server; «cloud» significa che la ospita il fornitore e paghi lui. Non citiamo prezzi fissi, verifica sempre il listino aggiornato del fornitore.

Promemoria degli endpoint

Per un riferimento rapido mentre configuri il nodo HTTP Request di n8n, la chiamata di invio testo di ogni fornitore, condensata:

Quale scegliere?

• Vuoi pieno controllo e zero costi per messaggio, e puoi gestire un server? Self-hosta Evolution API, WAHA o WPPConnect.
• Vuoi zero infrastruttura e la partenza più rapida? Usa un gateway cloud, Green API, UltraMsg, Whapi.cloud, Wassenger o Maytapi.
• Vuoi un nodo n8n di prima classe invece dell’HTTP grezzo? Evolution API (nodo community) o Wassenger (integrazione nativa).
• Devi gestire più numeri WhatsApp? Maytapi è fatta per questo.
• Ti serve il più grande ecosistema di template/community n8n? Evolution API.
• Ti servono messaggi conformi e consenzienti su scala reale? Passa all’API ufficiale con Wati invece di un gateway non ufficiale.

Ricevere messaggi e costruire un chatbot

Inviare è solo metà della storia. Ogni fornitore qui sopra può recapitare i messaggi in arrivo a un URL a tua scelta, punta quel webhook a un nodo Webhook di n8n e ogni messaggio WhatsApp in entrata diventa il trigger di un workflow. Lo schema bidirezionale classico è: messaggio in arrivo → cercare il mittente nei tuoi dati (un foglio, un CRM, un database) → eventualmente eseguire un passaggio IA che abbozza una risposta → rimandare la risposta attraverso lo stesso endpoint di invio. È un autoresponder o chatbot completo, costruito interamente con nodi n8n. Costruzioni comuni: un risponditore di FAQ che passa a un umano quando è in dubbio, notifiche di ordini o appuntamenti attivate da un foglio di calcolo, e assistenti IA che possono persino trascrivere le note vocali in arrivo (la gestione dei media di WAHA è particolarmente buona per questo).

Restare al sicuro, qualunque sia la scelta

• Usa un numero dedicato che sei disposto a perdere, non la tua linea personale principale.
• Scaldalo, parti piano e scrivi solo a persone che ti aspettano.
• Mai inviare a freddo messaggi di massa non richiesti; è la via più rapida al ban.
• Rispetta le disiscrizioni, mantieni volumi ragionevoli e aggiungi ritardi dall’aspetto umano tra i messaggi.

Domande frequenti

Le API non ufficiali di WhatsApp sono legali?

Sono molto usate, ma automatizzare così un numero WhatsApp personale può violare i Termini di servizio di WhatsApp, e Meta può bannare i numeri, soprattutto per invii di massa non richiesti. Usale per progetti personali e chat bidirezionale consenziente, e usa l’API ufficiale per il marketing su larga scala.

Devo scrivere codice per usarle con n8n?

Non proprio. In n8n puoi chiamarle tutte con il nodo HTTP Request, ed Evolution API e Wassenger hanno persino nodi dedicati. Configuri endpoint e token, nessuna programmazione tradizionale richiesta.

Qual è la migliore per i principianti?

Se non vuoi gestire un server, un’opzione cloud come Green API o UltraMsg è la più rapida. Se te la cavi con Docker e vuoi zero tariffe per messaggio, Evolution API o WAHA ti danno più controllo.

Cos’è il formato chat ID @c.us usato da alcuni fornitori?

È il numero del destinatario in formato internazionale completo (solo cifre) seguito da @c.us per una chat individuale, es. [email protected], o @g.us per un gruppo. Lo usano WAHA e Green API; gli altri accettano un semplice campo numero.

Le opzioni self-hosted sono davvero gratuite?

Sì, Evolution API e WPPConnect sono open-source e gratuite da self-hostare, e WAHA ha un core gratuito (più un livello Plus a pagamento). I tuoi unici costi sono il server su cui girano e, se lo usi, un piano n8n. Non ci sono tariffe per messaggio perché usano una sessione WhatsApp Web invece dell’API ufficiale a pagamento.

Possono far bannare il mio numero?

Tutte possono, se invii messaggi di massa non richiesti, non conta il gateway, conta il comportamento. Usa un numero dedicato, scrivi solo a chi ti aspetta, mantieni volumi modesti e valuta l’API ufficiale per le grandi campagne.