BroadRouter

在 n8n 中转写 WhatsApp 语音消息

更新于

用八个 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 语音消息指南中那段脚本的 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:

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 格式的工作流(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)中转换:

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 调用发出的是同一个请求:

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 兼容指南介绍了如何用同一个密钥让 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 错误码与重试。

准确率、方言,以及 BroadNet 的价格与其他语音转文字 API 的比较,见阿拉伯语语音转文字指南。如需 20 多款语音转文字产品的批量和流式标价(每项都附来源和核对日期),请看公开的语音转文字 API 价格索引。

常见问题

这个工作流能在 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 的费用另计。

以 Markdown 格式阅读问 ChatGPT问 Claude问 Perplexity