Workflow này biến từng tin nhắn thoại WhatsApp gửi đến thành văn bản ngay trong n8n. Đây là phiên bản n8n của script trong hướng dẫn tin nhắn thoại WhatsApp: cùng bước chuyển đổi bằng ffmpeg và cùng lệnh gọi chép lời. Tên node và tùy chọn dưới đây đã được đối chiếu với tài liệu và mã nguồn của n8n ngày 2026-11-14; các liên kết nằm trong phần nguồn.
Bạn cần gì
- n8n tự host. Tài liệu n8n cho biết node Execute Command không có trên n8n Cloud và bị tắt theo mặc định từ n8n 2.0.
- ffmpeg trên máy chủ n8n. Với Docker, lệnh chạy bên trong container n8n chứ không phải trên máy chủ Docker, nên image phải có ffmpeg.
- Một credential WhatsApp Business Cloud trong n8n, kết nối với một app Meta có WhatsApp Business Account của bạn, cùng access token của app đó.
- Một API key BroadNet. Tài khoản mới nhận $5 tín dụng ban đầu mà không cần thẻ, và cả hai model chép lời đều chạy được bằng khoản này.
Chuẩn bị n8n: ffmpeg, Execute Command và thư mục file
Image Docker chính thức của n8n không có trình quản lý gói. Tài liệu n8n hướng dẫn khôi phục apk trong một image tùy chỉnh để cài curl; cùng Dockerfile đó, thay curl bằng ffmpeg, sẽ cho bạn 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
Build bằng docker build -t n8n-ffmpeg . và chạy n8n-ffmpeg thay cho n8nio/n8n. Việc thay bằng ffmpeg là chỉnh sửa của chúng tôi trên ví dụ curl của n8n, nên hãy chạy ffmpeg -version một lần trong node Execute Command để xác nhận.
Sau đó đặt hai biến môi trường:
| Biến | Giá trị | Lý do |
|---|---|---|
NODES_EXCLUDE |
"[]" |
Execute Command bị chặn theo mặc định. Danh sách rỗng mở chặn nó, cùng mọi node khác mà n8n chặn mặc định, nên hãy thêm lại những node bạn muốn tiếp tục chặn. |
N8N_RESTRICT_FILE_ACCESS_TO |
để trống | Từ n8n 2.0, giá trị mặc định là ~/.n8n-files. Trong image chính thức, đó là /home/node/.n8n-files, thư mục dùng ở bên dưới. |
Workflow, từng node một
| # | Node | Cài đặt |
|---|---|---|
| 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, đường dẫn /home/node/.n8n-files/{{ $('WhatsApp Trigger').item.json.messages[0].audio.id }}.ogg, Input Binary Field data |
| 6 | Execute Command | lệnh ffmpeg bên dưới |
| 7 | Read/Write Files from Disk | Read File(s) From Disk, đường dẫn .wav, Put Output File in Field data |
| 8 | HTTP Request | POST tới endpoint chép lời, xem bên dưới |
Các node 5 đến 7 tồn tại vì Execute Command chạy một lệnh shell và không nhận dữ liệu binary của n8n, nên file phải được ghi ra đĩa rồi đọc lại.
Import workflow thay vì tự dựng
Tải workflow dạng JSON của n8n (8 node, cấu hình cho tiếng Ả Rập) và import vào n8n bằng Import from File. File không chứa key hay token nào. Mỗi node cần đăng nhập có một credential giữ chỗ với tên bắt đầu bằng REPLACE:; hãy mở bốn node đó và chọn credential của bạn. Tên loại node và tên tham số đã được đối chiếu với mã nguồn n8n ngày 2026-11-14; phần hướng dẫn dưới đây giải thích từng node, nên bạn cũng có thể tự dựng.
1–2. Kích hoạt khi có tin nhắn, chỉ giữ âm thanh
Trong mã nguồn n8n, WhatsApp Trigger xuất một item cho mỗi change trong webhook của Meta, với danh sách tin nhắn nằm dưới messages. Văn bản, hình ảnh và tin nhắn thoại đều đến qua sự kiện Messages, nên node If chỉ cho qua những item có tin nhắn đầu tiên mang type là audio. Thông báo đã gửi và đã đọc cũng đến qua cùng sự kiện nhưng không có danh sách messages; ?? '' biến giá trị thiếu đó thành chuỗi rỗng để phép kiểm tra kiểu nghiêm ngặt không lỗi.
WhatsApp chỉ cho phép một URL webhook đã đăng ký cho mỗi app. Tài liệu n8n cảnh báo rằng chuyển qua lại giữa URL test và URL production của trigger sẽ ghi đè nó, khiến URL còn lại không nhận được sự kiện.
3–4. Tải tin nhắn thoại từ Meta
Thao tác Download của node WhatsApp gọi endpoint media của Meta bằng media ID và trả về JSON có url, chứ không phải âm thanh. Tài liệu Meta cho biết URL đó có hiệu lực 5 phút và việc tải sẽ thất bại nếu thiếu access token. Vì vậy node HTTP Request tiếp theo tải {{ $json.url }} với token trong header Authorization và lưu phản hồi thành file trong trường data. Trong n8n, hãy lưu token trong một credential Header Auth (tên Authorization, giá trị là Bearer theo sau là token) thay vì gõ thẳng vào node.
5–7. Chuyển sang WAV bằng ffmpeg
Ghi file ra đĩa (node 5), rồi chuyển đổi trong node Execute Command (node 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 tạo WAV mono 16 kHz, đúng cách chuyển đổi mà tài liệu BroadNet dùng cho tin nhắn thoại. Media ID là một con số, nên dùng trong tên file là an toàn. Node 7 đọc file .wav trở lại trường data.
8. Chép lời
Tạo credential Header Auth thứ hai cho BroadNet (tên Authorization, giá trị là Bearer theo sau là key BroadNet của bạn). Sau đó cấu hình node HTTP Request cuối cùng:
| Trường | Giá trị |
|---|---|
| Method | POST |
| URL | https://inference.broadnet.ai/v1/audio/transcriptions |
| Authentication | Generic Credential Type, Header Auth, credential BroadNet |
| Send Body | bật, Body Content Type Form-Data |
Tham số body model |
broadnet/cohere-transcribe-arabic (hoặc broadnet/cohere-transcribe cho 13 ngôn ngữ còn lại) |
Tham số body language |
ar (hoặc en, es, …) |
Tham số body file |
Parameter Type n8n Binary File, Input Data Field Name data |
Phản hồi là JSON với bản chép lời trong text, nên các node sau đọc {{ $json.text }}. Đó cũng chính là request của lệnh curl này:
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
Luôn gửi language. Nếu thiếu, tiếng Ả Rập có thể bị trả về dưới dạng phiên âm sang chữ Latinh.
Làm gì với văn bản
Lưu vào CRM hoặc helpdesk, hoặc chuyển cho một chat model để tóm tắt hay phân loại tin nhắn. Hướng dẫn n8n tương thích OpenAI chỉ cách trỏ node OpenAI Chat Model của n8n tới BroadNet bằng cùng key. Để dọn dẹp, thêm một node Execute Command cuối cùng xóa hai file của media ID đó.
Xử lý sự cố
- Trigger không nhận được gì. Kiểm tra workflow đã được publish trên URL production và app Meta của bạn đã đăng ký với WhatsApp Business Account; tài liệu n8n cho biết n8n không tạo đăng ký đó.
- Tải media trả về 404. URL đã hết hạn sau 5 phút. Tài liệu Meta hướng dẫn yêu cầu một URL media mới, và gia hạn access token nếu vẫn thất bại.
- “Unrecognized node type” hoặc không thấy Execute Command. Node này bị chặn theo mặc định từ n8n 2.0; hãy đặt
NODES_EXCLUDE. ffmpeg: not found. Image không có ffmpeg; hãy build image tùy chỉnh ở trên.- Không được phép truy cập file. Ghi vào bên trong
/home/node/.n8n-files, hoặc đặtN8N_RESTRICT_FILE_ACCESS_TOthành thư mục bạn dùng. - 400, 413 hoặc 429 từ BroadNet. 413 nghĩa là file vượt quá 26.214.400 byte (khoảng 13 phút WAV mono 16 kHz); 429 nghĩa là quá nhiều request cùng lúc. Xem mã lỗi BroadNet và cách thử lại.
Độ chính xác, phương ngữ và cách giá của BroadNet so với các API chuyển giọng nói thành văn bản khác được trình bày trong hướng dẫn chuyển giọng nói tiếng Ả Rập thành văn bản. Để xem giá niêm yết batch và streaming của hơn 20 sản phẩm chuyển giọng nói thành văn bản, mỗi mục kèm nguồn và ngày kiểm tra, hãy xem bảng chỉ số giá API chuyển giọng nói thành văn bản mở.
