---
title: "n8n WhatsApp 语音消息转文字工作流分步教程 | BroadRouter"
description: "一个 n8n 工作流：接收 WhatsApp 语音消息，从 Meta 下载，用 ffmpeg 转换格式，再转写成阿拉伯语或其他 13 种语言的文字。"
url: https://broadrouter.com/zh/guides/n8n-whatsapp-voice-note-transcription/
lang: zh-Hans
updated: 2026-11-16
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

本页由英文原文借助 AI 翻译。[阅读英文原文](https://broadrouter.com/guides/n8n-whatsapp-voice-note-transcription/)（2026-11-16 更新）。

# 在 n8n 中转写 WhatsApp 语音消息

更新于 2026-11-16

用八个 n8n 节点：监听 Messages 的 WhatsApp Trigger、只保留音频的 If 节点、获取媒体 URL 的 WhatsApp Download 操作、下载 .ogg 文件的 HTTP Request、保存该文件的 Read/Write Files 节点、在 Execute Command 节点中用 ffmpeg 转成 WAV、加载 WAV 的第二个 Read/Write Files 节点，以及调用 /v1/audio/transcriptions 的 HTTP Request。需要自托管 n8n 并安装 ffmpeg。

这个工作流在 n8n 中把每条收到的 WhatsApp 语音消息转成文字。它是 [WhatsApp 语音消息指南中那段脚本](https://broadrouter.com/zh/guides/transcribe-whatsapp-voice-notes/)的 n8n 版本：同样的 ffmpeg 转换，同样的转写调用。下文的节点名和选项已于 2026-11-14 对照 n8n 的文档和源代码核对过，链接见参考来源。

## 准备条件

-   **自托管的 n8n。** n8n 的文档说，Execute Command 节点在 n8n Cloud 上不可用，并且从 n8n 2.0 起默认禁用。
-   **n8n 主机上装有 ffmpeg。** 使用 Docker 时，命令在 n8n 容器内运行，而不是在 Docker 宿主机上，所以 ffmpeg 必须在镜像里。
-   **n8n 中的 WhatsApp Business Cloud 凭据**，连接到一个关联了你的 WhatsApp Business Account 的 Meta 应用，以及该应用的访问令牌。
-   **一个 BroadNet API 密钥。** 新账户可获得 $5 初始额度，无需绑卡，两个转写模型都可以用它运行。

## 准备 n8n：ffmpeg、Execute Command 和文件目录

官方 n8n Docker 镜像没有包管理器。n8n 的文档演示了如何在自定义镜像中恢复 `apk` 来安装 curl；把同一个 Dockerfile 里的 `curl` 换成 `ffmpeg`，就能装上 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
```

用 `docker build -t n8n-ffmpeg .` 构建，然后用 `n8n-ffmpeg` 代替 `n8nio/n8n` 运行。把 curl 换成 `ffmpeg` 是我们对 n8n 示例做的改动，所以请先在 Execute Command 节点中运行一次 `ffmpeg -version` 确认。

然后设置两个环境变量：

| 变量 | 值 | 原因 |
| --- | --- | --- |
| `NODES_EXCLUDE` | `"[]"` | Execute Command 默认被禁用。空列表会解禁它，同时也会解禁 n8n 默认禁用的所有其他节点，所以请把仍想禁用的节点加回去。 |
| `N8N_RESTRICT_FILE_ACCESS_TO` | 不设置 | 从 n8n 2.0 起默认为 `~/.n8n-files`。在官方镜像中就是 `/home/node/.n8n-files`，也就是下文使用的目录。 |

## 工作流：逐个节点说明

| # | 节点 | 设置 |
| --- | --- | --- |
| 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 }}`，请求头 `Authorization: Bearer <WhatsApp access token>`，Response Format **File**，Put Output in Field `data` |
| 5 | Read/Write Files from Disk | **Write File to Disk**，路径 `/home/node/.n8n-files/{{ $('WhatsApp Trigger').item.json.messages[0].audio.id }}.ogg`，Input Binary Field `data` |
| 6 | Execute Command | 下文的 ffmpeg 命令 |
| 7 | Read/Write Files from Disk | **Read File(s) From Disk**，`.wav` 路径，Put Output File in Field `data` |
| 8 | HTTP Request | POST 到转写端点，见下文 |

之所以需要节点 5 到 7，是因为 Execute Command 运行的是 shell 命令，不接收 n8n 的二进制数据，所以文件要先写到磁盘再读回来。

### 直接导入工作流，不必手动搭建

[下载 n8n JSON 格式的工作流](https://broadrouter.com/downloads/n8n-whatsapp-voice-note-transcription.json)（8 个节点，已按阿拉伯语配置），在 n8n 中用 **Import from File** 导入。文件里不含任何密钥或令牌。每个需要登录的节点都有一个名称以 `REPLACE:` 开头的占位凭据；打开这四个节点，选上你自己的凭据即可。节点类型名和参数名已于 2026-11-14 对照 n8n 源代码核对；下文逐一解释每个节点，你也可以手动搭建。

### 1–2. 监听消息，只保留音频

从 n8n 的源码看，WhatsApp Trigger 对 Meta webhook 中的每个 change 输出一个 item，消息列表位于 `messages` 下。文本、图片和语音消息都通过 **Messages** 事件到达，所以 If 节点只放行第一条消息的 `type` 为 `audio` 的 item。送达回执和已读回执也走同一个事件，但没有 `messages` 列表；`?? ''` 会把这个缺失值变成空字符串，这样严格类型检查就不会因它们而失败。

WhatsApp 每个应用只允许注册一个 webhook URL。n8n 的文档提醒，在触发器的测试 URL 和生产 URL 之间切换会覆盖它，导致另一个 URL 收不到事件。

### 3–4. 从 Meta 下载语音消息

WhatsApp 节点的 **Download** 操作会用媒体 ID 调用 Meta 的媒体端点，返回的是带 `url` 的 JSON，而不是音频本身。Meta 的文档说，这个 URL 有效期为 5 分钟，没有访问令牌下载会失败。所以下一个 HTTP Request 节点在 `Authorization` 请求头中带上令牌去获取 `{{ $json.url }}`，并把响应作为文件保存在 `data` 字段中。在 n8n 中，请把令牌存到一个 **Header Auth** 凭据里（名称 `Authorization`，值为 `Bearer` 加令牌），不要直接填在节点里。

### 5–7. 用 ffmpeg 转成 WAV

先把文件写入磁盘（节点 5），然后在 Execute Command 节点（节点 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` 生成 16 kHz 单声道 WAV，这也是 BroadNet 文档中为语音消息使用的转换方式。媒体 ID 是一串数字，所以可以安全地用作文件名。节点 7 再把 `.wav` 文件读回 `data` 字段。

### 8\. 转写

为 BroadNet 再创建一个 **Header Auth** 凭据（名称 `Authorization`，值为 `Bearer` 加你的 BroadNet 密钥）。然后配置最后一个 HTTP Request 节点：

| 字段 | 值 |
| --- | --- |
| Method | POST |
| URL | `https://inference.broadnet.ai/v1/audio/transcriptions` |
| Authentication | Generic Credential Type，**Header Auth**，选择 BroadNet 凭据 |
| Send Body | 开启，Body Content Type 选 **Form-Data** |
| Body 参数 `model` | `broadnet/cohere-transcribe-arabic`（其他 13 种语言用 `broadnet/cohere-transcribe`） |
| Body 参数 `language` | `ar`（或 `en`、`es` 等） |
| Body 参数 `file` | Parameter Type 选 **n8n Binary File**，Input Data Field Name 填 `data` |

响应是 JSON，转写文本在 `text` 中，后续节点读取 `{{ $json.text }}` 即可。它与下面这条 curl 调用发出的是同一个请求：

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

务必发送 `language`。没有它，阿拉伯语可能会被音译成拉丁字母返回。

## 拿到文字之后

可以存入 CRM 或工单系统，或者交给对话模型来总结或分类消息。[n8n OpenAI 兼容指南](https://broadrouter.com/zh/guides/n8n-openai-compatible/)介绍了如何用同一个密钥让 n8n 的 OpenAI Chat Model 节点指向 BroadNet。如需清理，在最后加一个 Execute Command 节点，删除该媒体 ID 对应的两个文件。

## 故障排查

-   **触发器收不到任何东西。** 检查工作流是否已发布在生产 URL 上，以及你的 Meta 应用是否已订阅 WhatsApp Business Account；n8n 的文档说 n8n 不会创建这个订阅。
-   **媒体下载返回 404。** URL 在 5 分钟后过期了。Meta 的文档建议重新请求一个媒体 URL；如果仍然失败，就更新访问令牌。
-   **“Unrecognized node type”（无法识别的节点类型）或找不到 Execute Command。** 从 n8n 2.0 起它默认被禁用；设置 `NODES_EXCLUDE`。
-   **`ffmpeg: not found`。** 镜像里没有 ffmpeg；按上文构建自定义镜像。
-   **不允许访问该文件。** 写到 `/home/node/.n8n-files` 下，或者把 `N8N_RESTRICT_FILE_ACCESS_TO` 设为你使用的目录。
-   **BroadNet 返回 400、413 或 429。** 413 表示文件超过 26,214,400 字节（16 kHz 单声道 WAV 约 13 分钟）；429 表示同时发出的请求太多。参见 [BroadNet 错误码与重试](https://broadrouter.com/zh/guides/errors-and-retries/)。

准确率、方言，以及 BroadNet 的价格与其他语音转文字 API 的比较，见[阿拉伯语语音转文字指南](https://broadrouter.com/zh/guides/arabic-speech-to-text-api/)。如需 20 多款语音转文字产品的批量和流式标价（每项都附来源和核对日期），请看公开的[语音转文字 API 价格索引](https://broadrouter.com/data/speech-to-text-api-prices/)。

## 本指南涉及的术语

[API 密钥（API key）](https://broadrouter.com/zh/glossary/api-key/)

API 密钥是一串用于识别和授权 API 调用方的秘密字符串。大模型 API 通常要求把它放在 Authorization: Bearer 请求头里，任何持有该密钥的人都能发起请求，费用记在拥有该密钥的账户上。

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

WAV（Waveform Audio File Format，又称 WAVE）是建立在微软与 IBM 的 RIFF 格式之上的音频容器。它通常存放未压缩的线性 PCM 样本，因此大小可以预测：每秒字节数 = 采样率 × 每样本字节数 × 声道数。

## 常见问题

### 这个工作流能在 n8n Cloud 上运行吗？

按原样不行。n8n 的文档说 Execute Command 节点在 n8n Cloud 上不可用，而转换步骤需要运行 n8n 的机器上装有 ffmpeg。在 n8n Cloud 上，请在你自己控制的外部服务中转换音频，再用 HTTP Request 节点调用它。

### 为什么不能把 WhatsApp 的 .ogg 文件直接发给转写端点？

WhatsApp 语音消息是 Ogg 容器中的 Opus 音频。BroadNet 的转写端点接受 WAV 和 MP3，所以工作流会先用 ffmpeg 把每条语音转成 16 kHz 单声道 WAV。

### 为什么 WhatsApp 的 Download 操作返回的不是音频文件？

从 n8n 的源码看，Download 操作调用的是 Meta 的 GET 媒体端点，返回的是一个带临时 URL 的 JSON 对象。需要第二个 HTTP Request 节点带上你的 WhatsApp 访问令牌去下载该 URL。Meta 说这个 URL 的有效期是 5 分钟。

### 为什么发布工作流后 WhatsApp Trigger 收不到任何消息？

WhatsApp 每个应用只允许一个 webhook URL，所以在 n8n 的测试 URL 和生产 URL 之间切换会覆盖它。n8n 的文档还指出，n8n 不会帮你把 Meta 应用订阅到 WhatsApp Business Account；请在 Meta 的 Subscribed Apps API 中检查该订阅。

### 用这种方式转写 WhatsApp 语音消息要花多少钱？

BroadNet 按音频分钟计费：BroadNet Transcribe Arabic 为 $0.0042，BroadNet Transcribe 为 $0.002。10,000 条每条 30 秒的阿拉伯语语音消息费用为 $21.00。n8n 和 Meta 的费用另计。

## 相关指南

-   [用 API 把 WhatsApp 语音消息转成文字](https://broadrouter.com/zh/guides/transcribe-whatsapp-voice-notes/)
-   [在 n8n 中使用 BroadNet Inference（OpenAI 凭据与 Base URL）](https://broadrouter.com/zh/guides/n8n-openai-compatible/)
-   [阿拉伯语语音转文字 API 分步教程](https://broadrouter.com/zh/guides/arabic-speech-to-text-api/)
-   [BroadNet Inference 错误码，以及什么时候该重试](https://broadrouter.com/zh/guides/errors-and-retries/)
-   [所有可与 BroadNet Inference 配合使用的工具（英文）](https://broadrouter.com/integrations/)：SDK、编程智能体、聊天界面和自动化工具，并附每个工具的具体设置

用你的真实业务负载试一试。新账户可获得 US$5 初始额度，用于 Gemma和转写。DeepSeek、GLM和Qwen3.8 需要先充值。

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

**来源**

-   [n8n 文档：WhatsApp Trigger 节点（事件，每个应用一个 webhook；核对于 2026-11-14）](https://docs.n8n.io/integrations/builtin/trigger-nodes/n8n-nodes-base.whatsapptrigger/)
-   [n8n 文档：WhatsApp Business Cloud 节点（Media 操作；核对于 2026-11-14）](https://docs.n8n.io/integrations/builtin/app-nodes/n8n-nodes-base.whatsapp/)
-   [n8n 源代码：WhatsApp 媒体操作（Download 返回媒体 URL；核对于 2026-11-14）](https://github.com/n8n-io/n8n/blob/master/packages/nodes-base/nodes/WhatsApp/MediaDescription.ts)
-   [n8n 源代码：WhatsApp Trigger 输出（每个 webhook change value 一个 item；核对于 2026-11-14）](https://github.com/n8n-io/n8n/blob/master/packages/nodes-base/nodes/WhatsApp/WhatsAppTrigger.node.ts)
-   [n8n 文档：HTTP Request 节点（Form-Data、n8n Binary File、Response Format File；核对于 2026-11-14）](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.httprequest/)
-   [n8n 文档：Execute Command 节点（仅限自托管，n8n 2.0 起默认禁用，Docker 示例；核对于 2026-11-14）](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.executecommand/)
-   [n8n 文档：禁用节点（NODES\_EXCLUDE；核对于 2026-11-14）](https://docs.n8n.io/hosting/securing/blocking-nodes/)
-   [n8n 文档：Read/Write Files from Disk（N8N\_RESTRICT\_FILE\_ACCESS\_TO 默认值；核对于 2026-11-14）](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.readwritefile/)
-   [Meta WhatsApp Cloud API：媒体（下载需要访问令牌；URL 有效期 5 分钟；核对于 2026-11-14）](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media)
-   [Meta WhatsApp Cloud API：音频消息（语音消息为 OGG 容器的 Opus 音频；核对于 2026-11-14）](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/audio-messages)
-   [BroadNet Inference API 参考文档：转写（英文）](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=zh-guides-n8n-whatsapp-voice-note-transcription&utm_content=sources#requests)
