BroadRouter

Transcrever áudios do WhatsApp no n8n

Atualizado em

Use oito nós do n8n: um WhatsApp Trigger em Messages, um nó If que mantém só o áudio, a operação Download do WhatsApp para a URL da mídia, um HTTP Request que baixa o arquivo .ogg, um nó Read/Write Files que o salva, o ffmpeg em um nó Execute Command para gerar WAV, um segundo nó Read/Write Files que carrega o WAV e um HTTP Request para /v1/audio/transcriptions. É preciso n8n self-hosted com ffmpeg instalado.

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-files ou defina N8N_RESTRICT_FILE_ACCESS_TO com 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.

Perguntas frequentes

Esse workflow roda no n8n Cloud?

Não do jeito que está. A documentação do n8n diz que o nó Execute Command não está disponível no n8n Cloud, e a etapa de conversão precisa do ffmpeg na máquina que roda o n8n. No n8n Cloud, converta o áudio em um serviço externo que você controle e chame-o com um nó HTTP Request.

Por que não posso mandar o arquivo .ogg do WhatsApp direto para o endpoint de transcrição?

Os áudios do WhatsApp são áudio Opus em um contêiner Ogg. O endpoint de transcrição da BroadNet aceita WAV e MP3, então o workflow primeiro converte cada áudio para WAV mono de 16 kHz com o ffmpeg.

Por que a operação Download do WhatsApp não retorna o arquivo de áudio?

No código-fonte do n8n, a operação Download chama o endpoint GET de mídia da Meta, que retorna um objeto JSON com uma URL temporária. Um segundo nó HTTP Request baixa essa URL com o seu access token do WhatsApp. A Meta diz que a URL vale por 5 minutos.

Por que o meu WhatsApp Trigger não recebe nada depois que publico o workflow?

O WhatsApp permite uma URL de webhook por app, então alternar entre as URLs de teste e de produção do n8n sobrescreve essa URL. A documentação do n8n também avisa que o n8n não inscreve o seu app da Meta na WhatsApp Business Account; confira essa inscrição na Subscribed Apps API da Meta.

Quanto custa transcrever áudios do WhatsApp desse jeito?

A BroadNet cobra por minuto de áudio: $0.0042 com o BroadNet Transcribe Arabic ou $0.002 com o BroadNet Transcribe. 10.000 áudios em árabe de 30 segundos cada custam $21.00. As cobranças do n8n e da Meta são à parte.

Ler em MarkdownPerguntar ao ChatGPTPerguntar ao ClaudePerguntar ao Perplexity