이 워크플로는 들어오는 WhatsApp 음성 메시지를 n8n 안에서 하나하나 텍스트로 바꿉니다. WhatsApp 음성 메시지 가이드의 스크립트를 n8n으로 옮긴 것으로, ffmpeg 변환과 전사 호출이 같습니다. 아래 노드 이름과 옵션은 2026-11-14에 n8n 문서와 소스 코드로 확인했으며, 링크는 출처에 있습니다.
준비물
- 셀프 호스팅 n8n. n8n 문서에 따르면 Execute Command 노드는 n8n Cloud에서 쓸 수 없고, n8n 2.0부터 기본적으로 비활성화되어 있습니다.
- n8n 호스트의 ffmpeg. Docker에서는 명령이 Docker 호스트가 아니라 n8n 컨테이너 안에서 실행되므로, 이미지에 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 .로 빌드하고, n8nio/n8n 대신 n8n-ffmpeg를 실행하세요. ffmpeg로 바꾼 부분은 n8n의 curl 예제를 저희가 수정한 것이므로, 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가 셸 명령을 실행할 뿐 n8n 바이너리 데이터를 받지 않기 때문입니다. 그래서 파일을 디스크에 썼다가 다시 읽습니다.
직접 만드는 대신 워크플로 가져오기
n8n JSON 워크플로 다운로드(노드 8개, 아랍어용 설정)를 받아 n8n에서 Import from File로 가져오세요. 키나 토큰은 들어 있지 않습니다. 로그인이 필요한 노드에는 이름이 REPLACE:로 시작하는 자리표시자 자격 증명이 들어 있으니, 이 노드 네 개를 열어 각자의 자격 증명을 고르세요. 노드 타입 이름과 파라미터 이름은 2026-11-14에 n8n 소스 코드로 확인했습니다. 아래 가이드에서 노드를 하나씩 설명하므로 직접 만들 수도 있습니다.
1–2. 메시지에서 트리거하고 오디오만 남기기
n8n 소스를 보면 WhatsApp Trigger는 Meta 웹훅의 change마다 항목 하나를 출력하며, 메시지 목록은 messages 아래에 있습니다. 텍스트, 이미지, 음성 메시지가 모두 Messages 이벤트로 들어오므로, If 노드는 첫 메시지의 type이 audio인 항목만 통과시킵니다. 전달 확인과 읽음 확인도 같은 이벤트로 들어오지만 messages 목록이 없습니다. ?? ''가 이 빈 값을 빈 문자열로 바꿔 주므로 엄격한 타입 검사가 실패하지 않습니다.
WhatsApp은 앱당 등록된 웹훅 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은 16kHz 모노 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 |
응답은 text에 전사본이 담긴 JSON이므로, 이후 노드에서는 {{ $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를 반환함. 5분이 지나 URL이 만료된 것입니다. 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바이트(16kHz 모노 WAV로 약 13분)를 넘었다는 뜻이고, 429는 동시 요청이 너무 많다는 뜻입니다. BroadNet 오류 코드와 재시도를 참고하세요.
정확도, 방언, BroadNet 가격을 다른 음성 인식 API와 비교한 내용은 아랍어 음성 인식 가이드에서 다룹니다. 20개가 넘는 음성 인식 제품의 일괄 처리·스트리밍 정가를 출처와 확인 날짜와 함께 보려면 공개 음성 인식 API 가격 지수를 참고하세요.
