Questo workflow trasforma in testo, dentro n8n, ogni vocale WhatsApp in arrivo. È la versione n8n dello script della guida ai vocali WhatsApp: stessa conversione con ffmpeg e stessa chiamata di trascrizione. I nomi dei nodi e le opzioni qui sotto sono stati verificati sulla documentazione e sul codice sorgente di n8n il 2026-11-14; i link sono nelle fonti.
Cosa ti serve
- n8n self-hosted. La documentazione di n8n dice che il nodo Execute Command non è disponibile su n8n Cloud ed è disattivato per default da n8n 2.0.
- ffmpeg sull’host di n8n. Con Docker il comando gira dentro il container di n8n, non sull’host Docker, quindi ffmpeg deve essere nell’immagine.
- Una credenziale WhatsApp Business Cloud in n8n, collegata a un’app Meta con il tuo WhatsApp Business Account, e l’access token di quell’app.
- Una chiave API BroadNet. I nuovi account ricevono $5 di credito iniziale senza carta, e entrambi i modelli di trascrizione funzionano con quel credito.
Preparare n8n: ffmpeg, Execute Command e una cartella per i file
L’immagine Docker ufficiale di n8n non ha un package manager. La documentazione di n8n mostra come ripristinare apk in un’immagine personalizzata per installare curl; lo stesso Dockerfile con ffmpeg al posto di curl ti dà ffmpeg:
FROM n8nio/n8n
USER root
# Restore the apk package manager (removed from the base image)
COPY --from=alpine:3.22 /sbin/apk /sbin/apk
COPY --from=alpine:3.22 /lib/apk /lib/apk
COPY --from=alpine:3.22 /usr/lib/libapk* /usr/lib/
RUN apk add --no-cache ffmpeg
USER node
Costruiscila con docker build -t n8n-ffmpeg . ed esegui n8n-ffmpeg al posto di n8nio/n8n. Lo scambio con ffmpeg è una nostra modifica all’esempio con curl di n8n, quindi esegui una volta ffmpeg -version in un nodo Execute Command per verificarlo.
Poi imposta due variabili d’ambiente:
| Variabile | Valore | Perché |
|---|---|---|
NODES_EXCLUDE |
"[]" |
Execute Command è bloccato per default. Una lista vuota lo sblocca, insieme a tutti gli altri nodi che n8n blocca per default, quindi rimetti in lista quelli che vuoi tenere bloccati. |
N8N_RESTRICT_FILE_ACCESS_TO |
lasciala non impostata | Da n8n 2.0 il default è ~/.n8n-files. Nell’immagine ufficiale corrisponde a /home/node/.n8n-files, la cartella usata qui sotto. |
Il workflow, nodo per nodo
| # | Nodo | Impostazione |
|---|---|---|
| 1 | WhatsApp Trigger | Event: Messages |
| 2 | If | {{ $json.messages?.[0]?.type ?? '' }} is equal to audio |
| 3 | WhatsApp Business Cloud | Resource Media, Operation Download, Media ID {{ $json.messages[0].audio.id }} |
| 4 | HTTP Request | GET {{ $json.url }}, header Authorization: Bearer <WhatsApp access token>, Response Format File, Put Output in Field data |
| 5 | Read/Write Files from Disk | Write File to Disk, percorso /home/node/.n8n-files/{{ $('WhatsApp Trigger').item.json.messages[0].audio.id }}.ogg, Input Binary Field data |
| 6 | Execute Command | il comando ffmpeg qui sotto |
| 7 | Read/Write Files from Disk | Read File(s) From Disk, il percorso del .wav, Put Output File in Field data |
| 8 | HTTP Request | POST all’endpoint di trascrizione, qui sotto |
I nodi da 5 a 7 esistono perché Execute Command esegue un comando di shell e non accetta i dati binari di n8n, quindi il file passa dal disco e torna indietro.
Importare il workflow invece di costruirlo
Scarica il workflow in JSON per n8n (8 nodi, configurato per l’arabo) e importalo in n8n con Import from File. Non contiene chiavi né token. Ogni nodo che richiede un login ha una credenziale segnaposto il cui nome inizia con REPLACE:; apri quei quattro nodi e scegli le tue credenziali. I nomi dei tipi di nodo e dei parametri sono stati verificati sul codice sorgente di n8n il 2026-11-14; la guida qui sotto spiega ogni nodo, quindi puoi anche costruirlo a mano.
1–2. Trigger sui messaggi, solo audio
Nel codice sorgente di n8n, il WhatsApp Trigger produce un item per ogni change nel webhook di Meta, con l’elenco dei messaggi sotto messages. Testi, immagini e vocali arrivano tutti sull’evento Messages, quindi il nodo If lascia passare solo gli item il cui primo messaggio ha type impostato su audio. Le conferme di consegna e di lettura arrivano sullo stesso evento senza un elenco messages; il ?? '' trasforma quel valore mancante in una stringa vuota, così il controllo strict sul tipo non fallisce su di esse.
WhatsApp consente un solo URL di webhook registrato per app. La documentazione di n8n avverte che passare tra l’URL di test e quello di produzione del trigger lo sovrascrive, quindi l’altro URL smette di ricevere eventi.
3–4. Scaricare il vocale da Meta
L’operazione Download del nodo WhatsApp chiama l’endpoint media di Meta con l’ID del media e restituisce un JSON con un url, non l’audio. La documentazione di Meta dice che quell’URL vale 5 minuti e che il download fallisce senza il tuo access token. Per questo il nodo HTTP Request successivo scarica {{ $json.url }} con il token in un header Authorization e salva la risposta come file nel campo data. In n8n conserva il token in una credenziale Header Auth (nome Authorization, valore Bearer seguito dal token) invece di scriverlo nel nodo.
5–7. Convertire in WAV con ffmpeg
Scrivi il file su disco (nodo 5), poi convertilo nel nodo Execute Command (nodo 6):
ffmpeg -y -loglevel error -i /home/node/.n8n-files/{{ $('WhatsApp Trigger').item.json.messages[0].audio.id }}.ogg -ar 16000 -ac 1 /home/node/.n8n-files/{{ $('WhatsApp Trigger').item.json.messages[0].audio.id }}.wav
-ar 16000 -ac 1 produce un WAV mono a 16 kHz, la conversione che la documentazione di BroadNet usa per i vocali. L’ID del media è un numero, quindi è sicuro usarlo in un nome di file. Il nodo 7 rilegge il file .wav nel campo data.
8. Trascrivere
Crea una seconda credenziale Header Auth per BroadNet (nome Authorization, valore Bearer seguito dalla tua chiave BroadNet). Poi configura l’ultimo nodo HTTP Request:
| Campo | Valore |
|---|---|
| Method | POST |
| URL | https://inference.broadnet.ai/v1/audio/transcriptions |
| Authentication | Generic Credential Type, Header Auth, la credenziale BroadNet |
| Send Body | attivo, Body Content Type Form-Data |
Parametro del body model |
broadnet/cohere-transcribe-arabic (oppure broadnet/cohere-transcribe per le altre 13 lingue) |
Parametro del body language |
ar (oppure en, es, …) |
Parametro del body file |
Parameter Type n8n Binary File, Input Data Field Name data |
La risposta è un JSON con la trascrizione in text, quindi i nodi successivi leggono {{ $json.text }}. È la stessa richiesta di questa chiamata curl:
curl https://inference.broadnet.ai/v1/audio/transcriptions \
-H "Authorization: Bearer $BROADNET_API_KEY" \
-F model=broadnet/cohere-transcribe-arabic \
-F language=ar \
-F file=@voice-note.wav
Invia sempre language. Senza, l’arabo può tornare traslitterato in lettere latine.
Cosa fare con il testo
Salvalo nel tuo CRM o nel tuo helpdesk, oppure passalo a un modello di chat per riassumere o classificare il messaggio. La guida a n8n compatibile con OpenAI mostra come puntare il nodo OpenAI Chat Model di n8n su BroadNet con la stessa chiave. Per fare pulizia, aggiungi un ultimo nodo Execute Command che cancella i due file di quell’ID del media.
Risoluzione dei problemi
- Il trigger non riceve nulla. Controlla che il workflow sia pubblicato sull’URL di produzione e che la tua app Meta sia iscritta al WhatsApp Business Account; la documentazione di n8n dice che n8n non crea questa iscrizione.
- Il download del media restituisce 404. L’URL è scaduto dopo 5 minuti. La documentazione di Meta dice di richiedere un nuovo URL del media e, se anche questo fallisce, di rinnovare l’access token.
- “Unrecognized node type” o Execute Command manca. È bloccato per default da n8n 2.0; imposta
NODES_EXCLUDE. ffmpeg: not found. L’immagine non ha ffmpeg; costruisci l’immagine personalizzata descritta sopra.- L’accesso al file non è consentito. Scrivi sotto
/home/node/.n8n-files, oppure impostaN8N_RESTRICT_FILE_ACCESS_TOsulla cartella che usi. - 400, 413 o 429 da BroadNet. 413 significa che il file supera 26.214.400 byte (circa 13 minuti di WAV mono a 16 kHz); 429 significa troppe richieste contemporanee. Vedi codici di errore e retry di BroadNet.
Accuratezza, dialetti e il confronto tra il prezzo di BroadNet e quello di altre API di speech-to-text sono trattati nella guida allo speech-to-text in arabo. Per i prezzi di listino batch e streaming di oltre 20 prodotti di speech-to-text, ciascuno con la sua fonte e la data di verifica, vedi l’indice aperto dei prezzi delle API di speech-to-text.
