Este workflow transforma cada áudio recebido no WhatsApp em texto dentro do n8n. É a versão para n8n do script do guia de áudios do WhatsApp: a mesma conversão com ffmpeg e a mesma chamada de transcrição. Os nomes de nós e as opções abaixo foram conferidos na documentação e no código-fonte do n8n em 2026-11-14; os links estão nas fontes.
O que você precisa
- n8n self-hosted. A documentação do n8n diz que o nó Execute Command não está disponível no n8n Cloud e vem desativado por padrão a partir do n8n 2.0.
- ffmpeg no host do n8n. Com Docker, o comando roda dentro do container do n8n, não no host do Docker, então o ffmpeg precisa estar na imagem.
- Uma credencial WhatsApp Business Cloud no n8n, conectada a um app da Meta com a sua WhatsApp Business Account, e o access token desse app.
- Uma chave de API da BroadNet. Contas novas recebem $5 de crédito inicial sem cartão, e os dois modelos de transcrição rodam com ele.
Prepare o n8n: ffmpeg, Execute Command e uma pasta de arquivos
A imagem Docker oficial do n8n não tem gerenciador de pacotes. A documentação do n8n mostra como restaurar o apk em uma imagem personalizada para instalar o curl; o mesmo Dockerfile com ffmpeg no lugar de curl instala o 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
Faça o build com docker build -t n8n-ffmpeg . e rode n8n-ffmpeg no lugar de n8nio/n8n. A troca por ffmpeg é uma alteração nossa no exemplo com curl do n8n, então rode ffmpeg -version uma vez em um nó Execute Command para confirmar.
Depois defina duas variáveis de ambiente:
| Variável | Valor | Por quê |
|---|---|---|
NODES_EXCLUDE |
"[]" |
O Execute Command vem bloqueado por padrão. Uma lista vazia o desbloqueia, junto com todos os outros nós que o n8n bloqueia por padrão, então adicione de volta os que você quer manter bloqueados. |
N8N_RESTRICT_FILE_ACCESS_TO |
deixe sem definir | A partir do n8n 2.0, o padrão é ~/.n8n-files. Na imagem oficial, isso é /home/node/.n8n-files, a pasta usada abaixo. |
O workflow, nó por nó
| # | Nó | Configuração |
|---|---|---|
| 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, caminho /home/node/.n8n-files/{{ $('WhatsApp Trigger').item.json.messages[0].audio.id }}.ogg, Input Binary Field data |
| 6 | Execute Command | o comando ffmpeg abaixo |
| 7 | Read/Write Files from Disk | Read File(s) From Disk, o caminho do .wav, Put Output File in Field data |
| 8 | HTTP Request | POST para o endpoint de transcrição, abaixo |
Os nós 5 a 7 existem porque o Execute Command roda um comando de shell e não recebe dados binários do n8n, então o arquivo vai para o disco e volta.
Importe o workflow em vez de montá-lo
Baixe o workflow em JSON do n8n (8 nós, configurado para árabe) e importe no n8n com Import from File. Ele não contém chaves nem tokens. Cada nó que precisa de login tem uma credencial provisória cujo nome começa com REPLACE:; abra esses quatro nós e escolha as suas credenciais. Os nomes de tipos de nó e de parâmetros foram conferidos no código-fonte do n8n em 2026-11-14; o guia abaixo explica cada nó, então você também pode montá-lo à mão.
1–2. Disparar com mensagens, manter só áudio
No código-fonte do n8n, o WhatsApp Trigger gera um item para cada change no webhook da Meta, com a lista de mensagens em messages. Textos, imagens e áudios chegam todos no evento Messages, então o nó If deixa passar só os itens cuja primeira mensagem tem type igual a audio. Confirmações de entrega e de leitura chegam no mesmo evento sem a lista messages; o ?? '' transforma esse valor ausente em uma string vazia para que a verificação estrita de tipo não falhe nelas.
O WhatsApp permite uma URL de webhook registrada por app. A documentação do n8n avisa que alternar entre as URLs de teste e de produção do trigger sobrescreve essa URL, e a outra deixa de receber eventos.
3–4. Baixe o áudio da Meta
A operação Download do nó WhatsApp chama o endpoint de mídia da Meta com o ID da mídia e retorna um JSON com uma url, não o áudio. A documentação da Meta diz que essa URL vale por 5 minutos e que o download falha sem o seu access token. Por isso, o nó HTTP Request seguinte baixa {{ $json.url }} com o token em um header Authorization e salva a resposta como arquivo no campo data. No n8n, guarde o token em uma credencial Header Auth (nome Authorization, valor Bearer seguido do token) em vez de digitá-lo no nó.
5–7. Converta para WAV com ffmpeg
Grave o arquivo em disco (nó 5) e converta-o no nó Execute Command (nó 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 gera WAV mono de 16 kHz, a conversão que a documentação da BroadNet usa para áudios de voz. O ID da mídia é um número, então é seguro usá-lo em nome de arquivo. O nó 7 lê o arquivo .wav de volta para o campo data.
8. Transcreva
Crie uma segunda credencial Header Auth para a BroadNet (nome Authorization, valor Bearer seguido da sua chave da BroadNet). Depois configure o último nó HTTP Request:
| Campo | Valor |
|---|---|
| Method | POST |
| URL | https://inference.broadnet.ai/v1/audio/transcriptions |
| Authentication | Generic Credential Type, Header Auth, a credencial da BroadNet |
| Send Body | ativado, Body Content Type Form-Data |
Parâmetro de body model |
broadnet/cohere-transcribe-arabic (ou broadnet/cohere-transcribe para os outros 13 idiomas) |
Parâmetro de body language |
ar (ou en, es, …) |
Parâmetro de body file |
Parameter Type n8n Binary File, Input Data Field Name data |
A resposta é um JSON com a transcrição em text, então os nós seguintes leem {{ $json.text }}. É a mesma requisição desta chamada 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
Sempre envie language. Sem ele, o árabe pode voltar transliterado em letras latinas.
O que fazer com o texto
Salve no seu CRM ou help desk, ou passe para um modelo de chat resumir ou classificar a mensagem. O guia do n8n compatível com a OpenAI mostra como apontar o nó OpenAI Chat Model do n8n para a BroadNet com a mesma chave. Para fazer a limpeza, adicione um último nó Execute Command que apaga os dois arquivos daquele ID de mídia.
Solução de problemas
- O trigger não recebe nada. Confira se o workflow está publicado na URL de produção e se o seu app da Meta está inscrito na WhatsApp Business Account; a documentação do n8n diz que o n8n não cria essa inscrição.
- O download da mídia retorna 404. A URL expirou depois de 5 minutos. A documentação da Meta diz para pedir uma nova URL de mídia e, se isso também falhar, renovar o access token.
- “Unrecognized node type” ou o Execute Command não aparece. Ele vem bloqueado por padrão a partir do n8n 2.0; defina
NODES_EXCLUDE. ffmpeg: not found. A imagem não tem ffmpeg; faça o build da imagem personalizada acima.- Acesso ao arquivo não permitido. Grave em
/home/node/.n8n-filesou definaN8N_RESTRICT_FILE_ACCESS_TOcom a pasta que você usa. - 400, 413 ou 429 da BroadNet. 413 significa que o arquivo passa de 26.214.400 bytes (cerca de 13 minutos de WAV mono de 16 kHz); 429 significa requisições demais ao mesmo tempo. Veja códigos de erro e novas tentativas na BroadNet.
Precisão, dialetos e como o preço da BroadNet se compara ao de outras APIs de speech-to-text estão no guia de speech-to-text em árabe. Para preços de tabela em batch e streaming de mais de 20 produtos de speech-to-text, cada um com a fonte e a data da conferência, veja o índice aberto de preços de APIs de speech-to-text.
