Guida di configurazione

WhatsApp + n8n: invia e ricevi WhatsApp dai tuoi workflow

Funziona oggi con il nodo HTTP RequestUltima verifica: ottobre 2026

Spun ha una REST API costruita proprio per questo tipo di automazione, e n8n non ha bisogno di nulla di speciale per usarla: un nodo HTTP Request con un token Bearer invia messaggi WhatsApp, carica file multimediali, crea e aggiorna contatti, applica etichette e verifica se un numero ha WhatsApp. Un nodo trigger Webhook riceve indietro gli eventi WhatsApp reali, firmati così puoi dimostrare che arrivano da Spun.

Questa pagina è la strada che funziona oggi, scritta sulla API in produzione e non su una roadmap. Dove qualcosa non è ancora self-service, lo dice invece di far finta del contrario.

1. Crea una chiave API

  1. 1

    Apri le chiavi API

    Nella Posta in arrivo di Spun: “Impostazioni”, poi “Webhook”, poi “Gestisci Chiavi API”, poi “Nuova chiave”.

  2. 2

    Dagli un nome e scegli gli ambiti

    Chiamala per esempio “n8n Production”. Attiva solo ciò che serve al workflow: Send Messages per testo e file, Check Phone Numbers, Manage Contacts, Read Contacts, Manage Labels, Read Labels. Ogni endpoint qui sotto indica l’ambito che richiede.

  3. 3

    Copiala una volta sola

    La chiave inizia con wap_ e viene mostrata una sola volta. Conservala in n8n come credenziale, mai incollata nel parametro di un nodo, dove finirebbe nel log di esecuzione.

  4. 4

    Facoltativo: vincola la chiave al tuo server n8n

    Un n8n self-hosted ha un IP in uscita stabile, il che rende una chiave API molto più sicura del solito. Imposta “IP consentiti” sulla chiave con l’indirizzo in uscita del tuo n8n o con un intervallo CIDR, e una chiave rubata diventa inutile da qualsiasi altro posto. Lascia il campo vuoto e la chiave funziona da qualsiasi posto. Un errore qui non ti chiude mai fuori dalle Impostazioni, che usano il tuo accesso a Spun e non la chiave.

In n8n, aggiungi la chiave come credenziale Header Auth: nome dell’intestazione Authorization, valore dell’intestazione Bearer wap_YOUR_KEY. Riusa quell’unica credenziale in ogni nodo Spun di ogni workflow.

2. Invia messaggi WhatsApp da un workflow

Aggiungi un nodo HTTP Request, imposta metodo e URL, collega la credenziale Header Auth e invia JSON. Tutti gli endpoint si trovano sotto lo stesso URL di base, https://api.spun.com/api/integrations.

  • send-message (ambito: Send Messages): un messaggio di testo. Se il canale WhatsApp è offline, la API risponde 202 con un queue_id invece di fallire, e il messaggio parte quando il canale si riconnette.
  • send-media (Send Messages): un’immagine, un video, un file audio, una nota vocale o un documento, da un URL pubblico o da un caricamento base64, con una didascalia facoltativa su immagini, video e documenti.
  • check-phone (Check Phone Numbers): questo numero ha WhatsApp? Accetta fino a 20 numeri in una chiamata, quindi raggruppali invece di usare un ciclo.
  • create-contact e update-contact (Manage Contacts): mantieni sincronizzata la scheda di un lead da un modulo, un CRM o un foglio di calcolo. Se passi un numero di telefono, il contatto esistente viene aggiornato invece di crearne un duplicato.
  • contacts (Read Contacts): cerca un contatto per numero di telefono o per id.
  • apply-label e remove-label (Manage Labels): etichetta una chat da un trigger esterno, per esempio applica l’etichetta “Nuovo lead” a una chat nel momento in cui viene inviato un modulo.
  • labels (Read Labels): elenca le etichette dell’account, che è anche il modo più economico per verificare che una chiave funzioni.
Invia un messaggio WhatsApp (POST /api/integrations/send-message)
POST https://api.spun.com/api/integrations/send-message
Authorization: Bearer wap_YOUR_KEY
Content-Type: application/json

{
  "to": "15551234567",
  "text": "Hi {{ $json.first_name }}, thanks for getting in touch.",
  "idempotency_key": "{{ $execution.id }}"
}

Passa un idempotency_key negli invii e impostalo su un valore stabile per l’esecuzione, come {{ $execution.id }}. Se n8n ritenta il nodo, Spun riconosce la chiave invece di inviare il messaggio due volte.

3. Invia un file, un’immagine o una nota vocale

I file multimediali vanno a un endpoint separato. Fornisci esattamente uno tra media_url, che Spun scarica, o media_base64, che Spun carica prima per te.

  • type è uno tra image, video, audio, voice o document.
  • Una didascalia viene mantenuta su image, video e document. Audio e note vocali non hanno didascalia in WhatsApp.
  • Una nota vocale inviata come base64 viene convertita automaticamente nel formato che WhatsApp si aspetta. Una nota vocale passata come URL viene inviata esattamente com’è, quindi deve essere già ogg o opus; altrimenti inviala come base64 e lascia che Spun la converta.
  • I file multimediali di proposito non vengono messi in coda quando il canale è offline. Il testo va in coda, i file rispondono invece 409 channel_offline, perché riprodurre un messaggio multimediale in coda lo consegnerebbe come testo. Gestisci il 409 con i tentativi di n8n invece di trattarlo come un errore definitivo.
Invia un documento (POST /api/integrations/send-media)
POST https://api.spun.com/api/integrations/send-media
Authorization: Bearer wap_YOUR_KEY
Content-Type: application/json

{
  "type": "document",
  "to": "15551234567",
  "media_url": "https://example.com/invoice-1043.pdf",
  "filename": "invoice-1043.pdf",
  "caption": "Your invoice"
}

4. Avvia un workflow da un evento WhatsApp

  1. 1

    Crea prima il nodo Webhook

    Aggiungi un nodo trigger Webhook a un nuovo workflow e copiane il Production URL. n8n serve quell’URL solo mentre il workflow è attivo, quindi attivalo prima di fare i test.

  2. 2

    Incolla l’URL in Spun

    “Impostazioni”, poi “Webhook”, poi “Aggiungi webhook”. Incolla l’URL di n8n, scegli quali eventi devono attivarlo e salva. Spun firma ogni consegna con il segreto mostrato per quella sottoscrizione.

  3. 3

    Invia un messaggio di prova

    Scrivi dal tuo telefono al numero WhatsApp collegato. Il nodo Webhook riceve il payload reale, che diventa il campione su cui costruisci il resto del workflow.

  • Eventi a cui puoi iscriverti: messaggio in entrata, messaggio in uscita, contatto creato, contatto aggiornato, contatto eliminato, etichetta assegnata, flusso di chat completato, messaggio in coda elaborato, lead qualificato, chat archiviata e chiamata completata.
  • X-Webhook-Signature è un HMAC-SHA256 del corpo grezzo esatto della richiesta, scritto come sha256 seguito dal digest esadecimale. Verificalo sui byte del corpo grezzo, non su una copia riserializzata del JSON analizzato, perché l’ordine delle chiavi non è garantito dopo un parse e una nuova codifica.
  • Una consegna viene ritentata fino a tre volte, subito, poi dopo 5 secondi, poi dopo 30 secondi, e ogni tentativo attende 10 secondi una risposta. Qualsiasi 2xx conta come consegnato.
  • Per via di questi tentativi lo stesso evento può arrivare due volte. event_id resta uguale tra i tentativi di uno stesso evento, quindi usalo per scartare i duplicati.
Cosa invia Spun su message.inbound
POST https://your-n8n.example.com/webhook/abc123
X-Webhook-Event: message.inbound
X-Webhook-Delivery: 550e8400-e29b-41d4-a716-446655440000
X-Webhook-Signature: sha256=<hmac of the raw body>

{
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "message.inbound",
  "timestamp": "2026-08-18T10:30:00.000Z",
  "org_id": "123",
  "data": {
    "message_id": "[email protected]_ABC123",
    "chat_id": "[email protected]",
    "from": "15551234567",
    "type": "text",
    "text": "Hello!"
  }
}

Verificare la firma conta più di quanto sembri: l’URL del webhook è l’unica cosa che protegge il workflow, e gli URL dei webhook di n8n sono abbastanza indovinabili da valere la pena di verificare la firma.

Il payload del webhook WhatsApp, campo per campo

Gli eventi dei messaggi portano ciò che di solito un workflow deve ricavare da solo. Il numero del cliente arriva pronto da usare in formato internazionale, i gruppi sono segnalati, il nome e l’email del contatto Spun arrivano insieme quando Spun li ha, e i file multimediali arrivano come link firmato che il tuo workflow può scaricare per 24 ore.

  • peer_phone_e164 è null per i gruppi e per le chat senza un numero di telefono dietro.
  • Quando un file non ha finito l’elaborazione al momento dell’invio dell’evento, media_pending è true e media_url è null. L’evento non viene inviato di nuovo quando il file è pronto, quindi aggiungi una nota che rimandi alla conversazione in Spun.
  • conversation.closed scatta quando una chat viene archiviata in Spun e conversation.reopened quando viene ripresa: è così che un workflow tiene un ticket o una scheda allineati con la Posta in arrivo.
  • Chiudere o riaprire una conversazione dal tuo workflow passa per POST /api/integrations/conversations/close e /reopen, che richiedono sulla chiave l’ambito “Chiudi e riapri le conversazioni”.
Campi aggiuntivi su message.inbound e message.outbound (esempio)
{
  "is_group": false,
  "peer_phone_e164": "+15551234567",
  "contact_id": "8812",
  "contact_name": "Sarah Miller",
  "contact_email": "[email protected]",
  "type": "image",
  "text": null,
  "caption": "The damaged box",
  "media_url": "https://<signed link, valid for 24 hours>",
  "media_mime": "image/jpeg",
  "media_filename": null,
  "media_size": 182344,
  "media_pending": false
}

Vedi anche: Documentazione: ogni evento e campo, con i dettagli su firma e tentativi

Workflow pronti per gli helpdesk

Gli stessi webhook e la stessa API alimentano workflow n8n pronti che trasformano le conversazioni WhatsApp in ticket di helpdesk e rimandano su WhatsApp le risposte degli agenti. Ognuno ha una guida alla configurazione dedicata.

Vedi anche: Tutte le integrazioni WhatsApp con gli helpdesk · Zendesk · Zoho Desk · Freshdesk · HubSpot Service Hub · Jira Service Management

5. La descrizione completa della API

La descrizione completa e leggibile dalle macchine della API è pubblicata come documento OpenAPI 3.1, scaricabile gratis e senza bisogno di una chiave API. Contiene ogni endpoint, campo di richiesta, forma della risposta, codice di errore e l’envelope del webhook, il che di solito è più rapido che leggere una guida.

Specifica OpenAPI 3.1 pubblica
curl https://api.spun.com/api/integrations/openapi.json

n8n può importare direttamente una descrizione OpenAPI quando generi un nodo personalizzato o un nodo HTTP dichiarativo, quindi questa è la strada più breve da zero a un set di operazioni funzionante.

Un nodo Spun nativo per n8n

Tutto quello che c’è sopra usa il nodo generico HTTP Request, ed è per questo che funziona oggi senza attese. Un nodo community dedicato a Spun è pronto ed è in fase di pubblicazione: trasforma gli stessi endpoint in operazioni con un nome e campi veri, aggiunge una credenziale Spun con un test di connessione integrato e dà al lato trigger un nodo che si iscrive e si disiscrive da solo quando attivi o disattivi il workflow, verificando per te la firma di ogni consegna.

Non è ancora nel registro dei nodi community di n8n, quindi al momento non c’è nulla da installare e questa pagina non finge il contrario. Con lui arrivano due funzionalità: il trigger che si iscrive da solo, e il polling della cronologia dei messaggi a intervalli regolari per il caso in cui un’istanza n8n non possa ricevere webhook in entrata. Entrambe dipendono da permessi delle chiavi API che l’editor delle chiavi non offre ancora, quindi qui sono descritte invece di essere date come istruzioni.

Finché non è in elenco, il percorso HTTP Request di questa pagina è il modo supportato per usare Spun con n8n, e resta supportato anche dopo.

Cosa sapere prima di costruirci sopra

  • Il limite è di 60 richieste al minuto per chiave API, su tutti gli endpoint. Raggruppa le verifiche dei numeri fino a 20 per chiamata e metti un nodo Wait dentro qualsiasi ciclo che si espande su un elenco lungo.
  • remove-label richiede l’id dell’etichetta, a differenza di apply-label, che accetta anche il nome dell’etichetta. Chiama l’endpoint labels una volta all’inizio del workflow e conserva gli id.
  • Oggi le sottoscrizioni ai webhook si creano nelle Impostazioni di Spun. Uno strumento di workflow non può ancora creare la propria sottoscrizione con una chiave che puoi generare dall’editor delle chiavi.
  • È una API basata su chiavi. Non c’è una schermata OAuth “collega il tuo account Spun”, ed è voluto: le connessioni con gli assistenti IA usano un meccanismo separato, basato sul consenso, e chiavi separate, e le due cose non si possono mescolare su una stessa chiave.
  • Tutto è limitato al numero WhatsApp a cui appartiene la chiave. Un account con più numeri ha una chiave per numero invece di una chiave che li copra tutti.

Vedi anche: WhatsApp + Zapier e Make · WhatsApp + Google Sheets (completamente nativo, senza chiave API) · WhatsApp + HubSpot CRM

Domande frequenti

Devo aspettare un nodo Spun ufficiale per usare n8n?

No. Il nodo HTTP Request copre oggi ogni azione: invio di testo e file, contatti, etichette e verifiche dei numeri, con un nodo trigger Webhook per gli eventi in arrivo. Un nodo nativo è in pubblicazione per rendere le stesse cose più facili da configurare, non per renderle possibili.

C’è un nodo Spun nel registro community di n8n?

Non ancora. Il pacchetto è pronto ma non è in elenco, quindi al momento non c’è nulla da installare. La configurazione con HTTP Request di questa pagina funziona adesso e continua a funzionare dopo che il nodo sarà in elenco.

Come mi autentico?

Crea una chiave API in “Impostazioni”, poi “Webhook”, poi “Gestisci Chiavi API”, attiva solo gli ambiti che ti servono e conservala in n8n come credenziale Header Auth che invia Authorization: Bearer wap_YOUR_KEY. Puoi anche limitare la chiave all’indirizzo IP o all’intervallo del tuo server n8n.

Come evito che i tentativi di n8n inviino due volte lo stesso messaggio WhatsApp?

Invia un idempotency_key con la richiesta e mantienilo stabile per l’esecuzione, per esempio l’id di esecuzione di n8n. Spun riconosce una chiave ripetuta e restituisce il risultato originale invece di inviare di nuovo.

Come verifico che un webhook arrivi davvero da Spun?

Ogni consegna porta X-Webhook-Signature, un HMAC-SHA256 del corpo grezzo esatto calcolato con il segreto della sottoscrizione, nel formato sha256 seguito dal digest esadecimale. Calcola lo stesso HMAC sul corpo grezzo della richiesta e confronta. Usa i byte grezzi invece di ricodificare il JSON analizzato, perché l’ordine delle chiavi può cambiare e il confronto fallirebbe su consegne perfettamente valide.

Cosa succede se il canale WhatsApp è offline quando il mio workflow parte?

I messaggi di testo vengono accettati e messi in coda, e la risposta te lo dice con un id di coda che puoi interrogare. I file multimediali non vanno in coda e restituiscono invece un errore di canale offline, perché un messaggio multimediale in coda arriverebbe come semplice testo. Lascia che n8n ritenti quel nodo.

Quali sono i limiti di frequenza?

60 richieste al minuto per chiave API, su tutti gli endpoint. La verifica dei numeri accetta 20 numeri in una chiamata, che è il modo più semplice per restare ben sotto il limite quando convalidi un elenco.

Dove trovo il riferimento completo della API?

Una descrizione OpenAPI 3.1 di ogni endpoint è pubblicata su https://api.spun.com/api/integrations/openapi.json e per leggerla non serve una chiave API.

Prendi una chiave API e inizia a costruire

L’accesso alla API è incluso nei piani WhatsApp di Spun, insieme alla casella condivisa del team, alle risposte IA e alle integrazioni native con Google Sheets e HubSpot. Prezzo fisso da €45 al mese, prova gratuita.

Inizia gratis: 7 giorni con tutto incluso

Vedi tutte le integrazioni