BroadRouter

아랍어 WhatsApp 챗봇 아키텍처: 음성 메시지에서 답장까지

BroadNet Inference 팀 · 5분 분량 · 게시 · 업데이트

아랍어 WhatsApp 어시스턴트는 다섯 부분으로 이루어집니다. WhatsApp Business Platform에서 메시지를 받는 웹훅, 큐, 음성 메시지를 위한 음성 인식, 답장 초안을 쓰는 LLM, API로 답하는 발신기입니다. 음성 메시지를 변환해 BroadNet Transcribe Arabic으로 전사하는 비용은 오디오 1분당 $0.0042입니다.

아랍어 WhatsApp 챗봇에는 다섯 부분이 필요합니다. 공식 WhatsApp Business Platform에서 메시지를 받는 웹훅, 큐, 음성 메시지를 위한 음성 인식, 아랍어로 답장 초안을 쓰는 LLM, 그리고 WhatsApp의 24시간 시간 창 안에서 답하는 발신기입니다. 아랍어를 쓰는 고객 중에는 글을 치는 대신 방언으로 말하는 사람이 많기 때문에 음성 메시지가 중요합니다.

BroadRouter는 BroadNet이 운영하므로 예제는 BroadNet Inference를 씁니다. OpenAI 호환 음성 인식과 채팅을 제공하는 업체라면 어디든 같은 자리에 들어갈 수 있습니다.

아랍어 WhatsApp 챗봇은 어떤 부분으로 이루어지나요?

WhatsApp user
   │  text or voice note
   ▼
WhatsApp Business Platform (Cloud API)
   │  webhook POST
   ▼
1. Webhook receiver ── verify signature, store event, return 200
   │
   ▼
2. Queue (Redis, SQS, a database table)
   │
   ▼
3. Worker
   ├─ voice note? download media → ffmpeg → speech to text
   ├─ build prompt: system rules + recent history + new message
   └─ LLM drafts reply (or hands over to a human)
   │
   ▼
4. Sender ── POST /messages on the Cloud API
   │
   ▼
5. Store ── conversation state, opt-in status, audit log

1. 웹훅 수신기

WhatsApp Cloud API는 들어오는 메시지를 여러분이 등록한 웹훅으로 HTTPS POST 요청을 보내 전달합니다. 이 부분을 건강하게 유지하는 규칙이 두 가지 있습니다.

  • 모든 요청을 검증하세요. Meta 문서에 따르면 앱 시크릿으로 JSON 페이로드의 HMAC-SHA256을 계산해 X-Hub-Signature-256 헤더와 비교해야 합니다. 일치하지 않으면 모두 거부하세요.
  • 200을 빨리 돌려주세요. 이벤트를 저장하고 수신을 확인하세요. 웹훅 핸들러 안에서 오디오를 다운로드하거나 LLM을 호출하지 마세요. 전달에 실패하면 Meta는 “immediately, then a few more times with decreasing frequency over the next 7 days”(번역: 즉시, 그리고 이후 7일 동안 빈도를 줄여 가며 몇 번 더) 재시도하며, 중복 제거는 여러분이 처리하라고 안내합니다.

WhatsApp 메시지 ID를 멱등성 키로 쓰면, 웹훅이 다시 전달되어도 답장이 두 번 나가지 않습니다.

2. 큐

큐는 WhatsApp의 전달 타이밍과 여러분의 처리 시간을 분리합니다. 추론 한도에 맞게 동시성을 제한할 수도 있습니다. BroadNet 종량제 키는 분당 30개 요청과 동시 4개를 허용하므로, 429에서 재시도하는 작은 워커 풀이 알맞은 구조입니다. 오류와 재시도, 429 요청 한도 처리 방법을 참고하세요.

3. 워커: 음성 메시지를 텍스트로

음성 메시지라면 웹훅에 미디어 id, audio/ogg; codecs=opus 같은 mime_type, 그리고 WhatsApp에서 녹음한 경우 voice: true가 담긴 audio 객체가 들어 있습니다. 워커는 미디어 ID로 GET 요청을 보내 다운로드 URL을 얻고, 액세스 토큰으로 파일을 내려받은 뒤 변환하고 전사합니다. BroadNet 엔드포인트는 WAV나 MP3를 받으므로 먼저 변환하세요.

import os, subprocess, tempfile
from openai import OpenAI

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])

def transcribe_voice_note(ogg_bytes: bytes) -> str:
    with tempfile.TemporaryDirectory() as d:
        src, wav = os.path.join(d, "in.ogg"), os.path.join(d, "in.wav")
        open(src, "wb").write(ogg_bytes)
        subprocess.run(["ffmpeg", "-y", "-loglevel", "error", "-i", src,
                        "-ar", "16000", "-ac", "1", wav], check=True)
        with open(wav, "rb") as audio:
            return client.audio.transcriptions.create(
                model="broadnet/cohere-transcribe-arabic",
                file=audio,
                language="ar",   # without it, Arabic can come back in Latin letters
            ).text

임시 디렉터리는 호출이 끝나면 사라지므로 오디오가 디스크에 남지 않습니다. 내보낸 채팅을 일괄 처리하는 버전은 WhatsApp 음성 메시지 가이드에 있고, 형식과 제한은 아랍어 음성 인식 가이드에서 다룹니다. 파일은 26,214,400바이트(25MiB) 미만이어야 하는데, 일반적인 음성 메시지는 이보다 훨씬 작습니다.

3b. 워커: 답장 초안 쓰기

전사본은 입력된 메시지와 똑같이 다루되, 음성에서 나왔다는 사실은 모델에게 알려 주세요. 전사본에는 문장 부호가 없고 인식 오류가 있을 수 있기 때문입니다.

SYSTEM = """You are the WhatsApp assistant of a clinic in Dubai.
Customers write or speak in Gulf Arabic, other dialects, MSA, English or Arabizi.
Reply in simple Modern Standard Arabic unless the customer used English.
Keep replies under 60 words. Plain text only: no links, no markdown.
You can: answer opening hours, explain how to book, collect name and preferred time.
If the message is a complaint, medical question or you are unsure, reply that a
staff member will follow up, and set handover=true."""

def draft_reply(history: list[dict], text: str, from_voice: bool) -> str:
    note = "(transcribed voice note, may contain errors) " if from_voice else ""
    r = client.chat.completions.create(
        model="broadnet/qwen3.8-27b",
        max_tokens=1500,
        messages=[{"role": "system", "content": SYSTEM}, *history[-10:],
                  {"role": "user", "content": note + text}],
    )
    return r.choices[0].message.content

라우팅에는 자유 텍스트 대신 구조화된 출력(intent, handover, reply)을 요청하고 필드 값에 따라 처리하세요. 무료 JSON 스키마 생성기가 예시 답장에서 스키마를 만들어 줍니다. BroadNet 테스트에서 Qwen3.8 27B는 걸프와 이집트 방언을 이해하고 유창한 아랍어를 썼습니다. DeepSeek V4.1 Flash는 토큰당 더 저렴하며 BroadNet 무제한 플랜에서 쓰는 모델입니다. 두 모델 모두 답하기 전에 추론하므로 max_tokens에 여유를 두세요. 방언 처리는 LLM으로 다루는 걸프, 이집트, 레반트 아랍어에서 자세히 다룹니다.

4. 발신기

답장은 여러분의 전화번호 ID에 해당하는 Cloud API messages 엔드포인트로 나갑니다. 대화형 답장은 일반 텍스트로 보내세요. WhatsApp 서식(굵게, 목록)은 표시되지만 Markdown 표와 제목은 표시되지 않으므로, 모델에게 이런 것을 만들지 말라고 지시하세요.

5. 저장소

대화 상태(대부분의 지원 봇에는 최근 10턴이면 충분합니다), 고객의 수신 동의 상태, 그리고 봇이 무엇을 왜 보냈는지 남기는 감사 로그를 보관하세요. 필요 이상으로 저장하지 마세요. 음성 메시지 전사본에는 이름, 주소, 건강 정보가 들어 있는 경우가 많습니다.

챗봇에는 어떤 WhatsApp 정책 규칙이 적용되나요?

WhatsApp은 비즈니스가 서비스를 쓰는 방식에 엄격하며, 이 규칙은 고객만큼이나 여러분의 번호도 보호합니다. 출시 전에 WhatsApp Business Messaging Policy를 읽으세요. 실무에서는 다음과 같습니다.

  1. 수신 동의가 먼저입니다. 정책상 연락할 수 있는 사람은 번호를 알려 주고 WhatsApp으로 연락받는 데 동의한 사람뿐입니다. 고객이 먼저 메시지를 보냈다고 마케팅에 동의한 것은 아닙니다.
  2. 원치 않는 메시지 금지. 정책에는 “Do not confuse, deceive, defraud, mislead, spam, or surprise people with your communications.”(번역: 커뮤니케이션으로 사람들을 혼란스럽게 하거나, 속이거나, 사기를 치거나, 오도하거나, 스팸을 보내거나, 놀라게 하지 마세요.)라고 되어 있습니다. 연락해 오지 않았거나 수신에 동의하지 않은 사람에게 먼저 메시지를 보내지 마세요.
  3. 24시간 고객 서비스 시간 창을 지키세요. 고객의 마지막 메시지 이후 24시간 안에는 자유 형식 답장을 보낼 수 있습니다. 그 밖에서는 승인된 메시지 템플릿만 보낼 수 있습니다.
  4. 사람 상담원을 제공하세요. 24시간 시간 창 안에서는 자동 답장이 허용되지만, 정책은 사람에게 연결되는 “prompt, clear, and direct escalation paths”(번역: 신속하고 명확하며 직접적인 에스컬레이션 경로)를 요구합니다.
  5. 수신 거부를 존중하세요. 정책상 차단, 중단, 수신 거부 요청은 모두 존중해야 합니다. “stop”이나 “توقف”도 그런 요청으로 취급하세요.

하나 더 있는데, 이는 Meta가 아니라 저희의 규칙입니다. 새 연락처에 보내는 첫 답장은 단순하게 하세요. URL 없는 짧은 일반 텍스트 답장이 가장 안전합니다. 낯선 비즈니스가 보낸 링크 가득한 메시지는 사용자에게 스팸처럼 보이고, 사용자는 여러분을 차단하고 신고할 수 있습니다. 링크는 고객이 요청할 때 나중에 공유하세요.

아랍어 WhatsApp 봇 운영 비용은 얼마인가요?

음성 인식은 오디오 분 단위로 과금됩니다. BroadNet Transcribe Arabic 기준입니다.

물량 비용
음성 메시지 1분 $0.0042
음성 메시지 1시간 $0.25
30초짜리 음성 메시지 10,000개 $21.00

LLM 답장은 종량제에서 토큰 단위로 과금됩니다. 100만 토큰당 Qwen3.8 27B는 입력 $0.175, 출력 $2.17이고, DeepSeek V4.1 Flash는 입력 $0.175, 출력 $0.52입니다. 10턴의 대화 기록이 붙은 지원 답장은 추론을 포함해 수천 토큰이므로, 답장 하나의 비용은 위 100만 토큰당 가격의 몇천분의 일입니다. 월간 금액은 무료 LLM API 비용 계산기에 메시지 물량을 넣어 확인하세요. 봇이 하루 종일 DeepSeek V4.1 Flash로 돌아간다면 가격 페이지의 $60 Full Moon 플랜과 비교해 보세요.

음성 메시지의 개인정보는 어떻게 보호하나요?

음성 메시지는 비즈니스가 다루는 데이터 중 가장 개인적인 것에 속합니다. BroadNet Inference는 요청이 끝난 뒤 오디오, 프롬프트, 전사본을 보관하지 않지만(데이터 비보관 참고), 이는 추론 단계에만 해당합니다. 여러분의 큐, 로그, 데이터베이스가 전사본을 얼마나 보관할지 정하고, 처리가 끝난 미디어 파일은 삭제하세요.

출시 체크리스트

  • 웹훅 서명을 검증하고, 처리하기 전에 200을 반환합니다.
  • WhatsApp 메시지 ID로 멱등성을 보장합니다.
  • 음성 메시지를 WAV로 변환하고 language=ar로 전사합니다.
  • 워커 풀 크기를 요청 한도에 맞추고, 429에서 백오프합니다.
  • 시스템 프롬프트에 방언, 문체, 길이, “링크 금지”를 지정합니다.
  • 사람 상담원 연결 경로를 테스트했습니다.
  • 수신 동의를 기록하고, 원치 않는 발송은 하지 않으며, 24시간 시간 창 밖에서는 템플릿만 씁니다.
  • 전사본을 정해진 일정에 따라 삭제합니다.

답장하는 봇이 아니라 음성 메시지를 티켓으로 바꾸는 것만 필요하다면, 더 단순한 파이프라인을 다루는 비즈니스용 음성 메시지 텍스트 변환을 참고하세요.

자주 묻는 질문

나에게 연락한 적 없는 고객에게 메시지를 보내도 되나요?

해당 고객이 우리 비즈니스의 메시지를 받겠다고 동의했고, 승인된 메시지 템플릿을 쓰는 경우에만 가능합니다. 원치 않는 메시지는 WhatsApp 정책 위반이며 번호가 제한될 수 있습니다.

전사하기 전에 음성 메시지를 왜 변환해야 하나요?

WhatsApp 음성 메시지는 Ogg/Opus 파일이고, BroadNet 전사 엔드포인트는 WAV나 MP3를 받습니다. ffmpeg 명령 하나로 16kHz 모노 WAV로 변환할 수 있습니다.

답장 초안은 어떤 LLM이 써야 하나요?

내 메시지로 테스트하세요. BroadNet은 자체 테스트에서 Qwen3.8 27B가 걸프와 이집트 방언을 이해하고 유창한 아랍어를 썼다고 밝힙니다. DeepSeek V4.1 Flash는 토큰당 더 저렴하고 정액 플랜에서도 쓸 수 있습니다.

WhatsApp 봇은 템플릿 없이 언제까지 답장할 수 있나요?

고객의 마지막 메시지 이후 24시간 동안의 고객 서비스 시간 창 안에서는 자유 형식 답장을 보낼 수 있습니다. 그 밖에서는 WhatsApp Business Messaging Policy상 승인된 메시지 템플릿만 보낼 수 있습니다.

WhatsApp 챗봇에 상담원 연결이 필요한가요?

네. 정책은 자동화를 허용하지만, 채팅 내 상담원 연결, 전화번호, 이메일, 지원 양식처럼 신속하고 명확하며 직접적인 에스컬레이션 경로를 요구합니다.

BroadNet이 음성 메시지를 보관하나요?

아니요. BroadNet Inference는 요청을 처리하는 동안만 오디오와 전사본을 다루고 보관하지 않습니다. 다만 여러분의 서버와 WhatsApp에는 여전히 사본이 남으므로, 그쪽의 보관 정책도 정해 두세요.

Markdown으로 읽기ChatGPT에 질문하기Claude에 질문하기Perplexity에 질문하기