---
title: "n8n WhatsApp voice note transcription workflow, step by step"
description: "An n8n workflow that receives a WhatsApp voice note, downloads it from Meta, converts it with ffmpeg and transcribes it in Arabic or 13 other languages."
url: https://broadrouter.com/guides/n8n-whatsapp-voice-note-transcription/
lang: en
updated: 2026-11-16
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

# Transcribe WhatsApp voice notes in n8n

Updated 2026-11-16

Use eight n8n nodes: a WhatsApp Trigger on Messages, an If node that keeps audio, WhatsApp Download for the media URL, an HTTP Request that fetches the .ogg file, Read/Write Files to save it, ffmpeg in Execute Command to make WAV, Read/Write Files to load the WAV, and an HTTP Request to /v1/audio/transcriptions. It needs self-hosted n8n with ffmpeg.

This workflow turns each incoming WhatsApp voice note into text inside n8n. It is the n8n version of the [script in the WhatsApp voice notes guide](https://broadrouter.com/guides/transcribe-whatsapp-voice-notes/): the same ffmpeg conversion and the same transcription call. Node names and options below were checked against n8n’s documentation and source code on 2026-11-14; the links are in the sources.

## What you need

-   **Self-hosted n8n.** n8n’s docs say the Execute Command node is not available on n8n Cloud and is disabled by default from n8n 2.0.
-   **ffmpeg on the n8n host.** With Docker, the command runs inside the n8n container, not on the Docker host, so ffmpeg must be in the image.
-   **A WhatsApp Business Cloud credential in n8n**, connected to a Meta app with your WhatsApp Business Account, and the access token for that app.
-   **A BroadNet API key.** New accounts get $5 of starting credit with no card, and both transcription models run on it.

## Prepare n8n: ffmpeg, Execute Command and a file folder

The official n8n Docker image has no package manager. n8n’s docs show how to restore `apk` in a custom image to install curl; the same Dockerfile with `ffmpeg` in place of `curl` gives you ffmpeg:

```dockerfile
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
```

Build it with `docker build -t n8n-ffmpeg .` and run `n8n-ffmpeg` in place of `n8nio/n8n`. The `ffmpeg` swap is our change to n8n’s curl example, so run `ffmpeg -version` in an Execute Command node once to confirm it.

Then set two environment variables:

| Variable | Value | Why |
| --- | --- | --- |
| `NODES_EXCLUDE` | `"[]"` | Execute Command is blocked by default. An empty list unblocks it, and every other node n8n blocks by default, so add back any you want to keep blocked. |
| `N8N_RESTRICT_FILE_ACCESS_TO` | leave unset | From n8n 2.0 it defaults to `~/.n8n-files`. In the official image that is `/home/node/.n8n-files`, the folder used below. |

## The workflow, node by node

| # | Node | Setting |
| --- | --- | --- |
| 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**, path `/home/node/.n8n-files/{{ $('WhatsApp Trigger').item.json.messages[0].audio.id }}.ogg`, Input Binary Field `data` |
| 6 | Execute Command | the ffmpeg command below |
| 7 | Read/Write Files from Disk | **Read File(s) From Disk**, the `.wav` path, Put Output File in Field `data` |
| 8 | HTTP Request | POST to the transcription endpoint, below |

Nodes 5 to 7 exist because Execute Command runs a shell command and does not take n8n binary data, so the file goes to disk and back.

### Import the workflow instead of building it

[Download the workflow as n8n JSON](https://broadrouter.com/downloads/n8n-whatsapp-voice-note-transcription.json) (8 nodes, set up for Arabic) and import it in n8n with **Import from File**. It contains no keys or tokens. Each node that needs a login has a placeholder credential whose name starts with `REPLACE:`; open those four nodes and pick your own credentials. Node type names and parameter names were checked against n8n’s source code on 2026-11-14; the guide below explains each node, so you can also build it by hand.

### 1–2. Trigger on messages, keep audio only

In n8n’s source, the WhatsApp Trigger outputs one item per change in Meta’s webhook, with the message list under `messages`. Text, images and voice notes all arrive on the **Messages** event, so the If node passes on only items whose first message has `type` set to `audio`. Delivery and read receipts arrive on the same event with no `messages` list; the `?? ''` turns that missing value into an empty string so the strict type check does not fail on them.

WhatsApp allows one registered webhook URL per app. n8n’s docs warn that switching between the trigger’s test and production URLs overwrites it, so the other URL stops receiving events.

### 3–4. Download the voice note from Meta

The WhatsApp node’s **Download** operation calls Meta’s media endpoint with the media ID and returns JSON with a `url`, not the audio. Meta’s docs say that URL is valid for 5 minutes and that the download fails without your access token. So the next HTTP Request node fetches `{{ $json.url }}` with the token in an `Authorization` header and saves the response as a file in the `data` field. In n8n, store the token in a **Header Auth** credential (name `Authorization`, value `Bearer` followed by the token) rather than typing it into the node.

### 5–7. Convert to WAV with ffmpeg

Write the file to disk (node 5), then convert it in the Execute Command node (node 6):

```bash
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` makes 16 kHz mono WAV, the conversion BroadNet’s docs use for voice notes. The media ID is a number, so it is safe to use in a file name. Node 7 reads the `.wav` file back into the `data` field.

### 8\. Transcribe

Create a second **Header Auth** credential for BroadNet (name `Authorization`, value `Bearer` followed by your BroadNet key). Then configure the last HTTP Request node:

| Field | Value |
| --- | --- |
| Method | POST |
| URL | `https://inference.broadnet.ai/v1/audio/transcriptions` |
| Authentication | Generic Credential Type, **Header Auth**, the BroadNet credential |
| Send Body | on, Body Content Type **Form-Data** |
| Body parameter `model` | `broadnet/cohere-transcribe-arabic` (or `broadnet/cohere-transcribe` for the other 13 languages) |
| Body parameter `language` | `ar` (or `en`, `es`, …) |
| Body parameter `file` | Parameter Type **n8n Binary File**, Input Data Field Name `data` |

The response is JSON with the transcript in `text`, so later nodes read `{{ $json.text }}`. That is the same request as this curl call:

```bash
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
```

Always send `language`. Without it, Arabic can come back transliterated into Latin letters.

## What to do with the text

Save it to your CRM or helpdesk, or pass it to a chat model to summarise or classify the message. The [n8n OpenAI-compatible guide](https://broadrouter.com/guides/n8n-openai-compatible/) shows how to point n8n’s OpenAI Chat Model node at BroadNet with the same key. To clean up, add a final Execute Command node that deletes the two files for that media ID.

## Troubleshooting

-   **The trigger gets nothing.** Check that the workflow is published on the production URL and that your Meta app is subscribed to the WhatsApp Business Account; n8n’s docs say n8n does not create that subscription.
-   **The media download returns 404.** The URL expired after 5 minutes. Meta’s docs say to request a new media URL, and to renew the access token if that also fails.
-   **“Unrecognized node type” or Execute Command is missing.** It is blocked by default from n8n 2.0; set `NODES_EXCLUDE`.
-   **`ffmpeg: not found`.** The image has no ffmpeg; build the custom image above.
-   **Access to the file is not allowed.** Write under `/home/node/.n8n-files`, or set `N8N_RESTRICT_FILE_ACCESS_TO` to the folder you use.
-   **400, 413 or 429 from BroadNet.** 413 means the file is over 26,214,400 bytes (about 13 minutes of 16 kHz mono WAV); 429 means too many requests at once. See [BroadNet error codes and retries](https://broadrouter.com/guides/errors-and-retries/).

Accuracy, dialects and how BroadNet’s price compares with other speech-to-text APIs are covered in the [Arabic speech-to-text guide](https://broadrouter.com/guides/arabic-speech-to-text-api/). For batch and streaming list prices of more than 20 speech-to-text products, each with its source and the date checked, see the open [speech-to-text API price index](https://broadrouter.com/data/speech-to-text-api-prices/).

## Terms in this guide

[Token](https://broadrouter.com/glossary/token/)

A token is the unit of text a language model reads and writes: a word, part of a word, a punctuation mark or a byte sequence produced by the model's tokenizer. LLM APIs count, limit and usually bill usage in tokens.

[Speech-to-text](https://broadrouter.com/glossary/speech-to-text/)

Speech-to-text, also called automatic speech recognition (ASR), is technology that converts spoken audio into written text. A speech-to-text API accepts an audio file or stream and returns a transcript, usually priced per minute of audio. Accuracy is measured with word error rate and varies with accent, dialect and recording quality.

[WAV](https://broadrouter.com/glossary/wav/)

WAV (Waveform Audio File Format, or WAVE) is an audio container built on Microsoft and IBM's RIFF format. It usually holds uncompressed linear PCM samples, so its size is predictable: sample rate times bytes per sample times channels, per second.

[API key](https://broadrouter.com/glossary/api-key/)

An API key is a secret string that identifies and authorizes a client calling an API. LLM APIs usually expect it in an Authorization: Bearer header, and anyone who holds the key can make requests that are billed to the account that owns it.

[Streaming](https://broadrouter.com/glossary/streaming/)

Streaming is a way of returning a language model response in small chunks while it is still being generated, instead of as one reply at the end. OpenAI-compatible APIs stream over server-sent events when the request sets stream to true.

## Questions

### Does this workflow run on n8n Cloud?

Not as written. n8n's docs say the Execute Command node isn't available on n8n Cloud, and the conversion step needs ffmpeg on the machine that runs n8n. On n8n Cloud, convert the audio in an outside service you control and call it with an HTTP Request node.

### Why can't I send the WhatsApp .ogg file straight to the transcription endpoint?

WhatsApp voice notes are Opus audio in an Ogg container. BroadNet's transcription endpoint accepts WAV and MP3, so the workflow converts each note to 16 kHz mono WAV with ffmpeg first.

### Why does the WhatsApp Download operation not return the audio file?

In n8n's source, the Download operation calls Meta's GET media endpoint, which returns a JSON object with a temporary URL. A second HTTP Request node fetches that URL with your WhatsApp access token. Meta says the URL is valid for 5 minutes.

### Why does my WhatsApp Trigger receive nothing after I publish the workflow?

WhatsApp allows one webhook URL per app, so switching between n8n's test and production URLs overwrites it. n8n's docs also note that n8n does not subscribe your Meta app to the WhatsApp Business Account; check that subscription in Meta's Subscribed Apps API.

### How much does it cost to transcribe WhatsApp voice notes this way?

BroadNet bills per audio minute: $0.0042 with BroadNet Transcribe Arabic or $0.002 with BroadNet Transcribe. 10,000 Arabic voice notes of 30 seconds each cost $21.00. n8n and Meta charges are separate.

## Related guides

-   [Transcribe WhatsApp voice notes to text with an API](https://broadrouter.com/guides/transcribe-whatsapp-voice-notes/)
-   [Use BroadNet Inference in n8n (OpenAI credential, Base URL)](https://broadrouter.com/guides/n8n-openai-compatible/)
-   [Arabic speech-to-text API, step by step](https://broadrouter.com/guides/arabic-speech-to-text-api/)
-   [BroadNet Inference error codes and when to retry](https://broadrouter.com/guides/errors-and-retries/)
-   [All tools that work with BroadNet Inference](https://broadrouter.com/integrations/): SDKs, coding agents, chat UIs and automation tools, with exact settings for each

Try it on your real workload. New accounts start with $5 of credit for Gemma and transcription. DeepSeek, GLM and Qwen3.8 need a top-up.

[Get started](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=guides-n8n-whatsapp-voice-note-transcription&utm_content=page-cta) ·

**Sources**

-   [n8n docs, WhatsApp Trigger node (events, one webhook per app; checked 2026-11-14)](https://docs.n8n.io/integrations/builtin/trigger-nodes/n8n-nodes-base.whatsapptrigger/)
-   [n8n docs, WhatsApp Business Cloud node (Media operations; checked 2026-11-14)](https://docs.n8n.io/integrations/builtin/app-nodes/n8n-nodes-base.whatsapp/)
-   [n8n source, WhatsApp media operations (Download returns the media URL; checked 2026-11-14)](https://github.com/n8n-io/n8n/blob/master/packages/nodes-base/nodes/WhatsApp/MediaDescription.ts)
-   [n8n source, WhatsApp Trigger output (one item per webhook change value; checked 2026-11-14)](https://github.com/n8n-io/n8n/blob/master/packages/nodes-base/nodes/WhatsApp/WhatsAppTrigger.node.ts)
-   [n8n docs, HTTP Request node (Form-Data, n8n Binary File, Response Format File; checked 2026-11-14)](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.httprequest/)
-   [n8n docs, Execute Command node (self-hosted only, disabled by default from n8n 2.0, Docker example; checked 2026-11-14)](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.executecommand/)
-   [n8n docs, blocking nodes (NODES\_EXCLUDE; checked 2026-11-14)](https://docs.n8n.io/hosting/securing/blocking-nodes/)
-   [n8n docs, Read/Write Files from Disk (N8N\_RESTRICT\_FILE\_ACCESS\_TO default; checked 2026-11-14)](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.readwritefile/)
-   [Meta WhatsApp Cloud API, media (download needs the access token; URL valid 5 minutes; checked 2026-11-14)](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media)
-   [Meta WhatsApp Cloud API, audio messages (voice notes are OGG with Opus; checked 2026-11-14)](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/audio-messages)
-   [BroadNet Inference API reference, transcription](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=guides-n8n-whatsapp-voice-note-transcription&utm_content=sources#requests)
