这个工作流在 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 价格索引。
