Chatbot WhatsApp tiếng Ả Rập cần năm phần: một webhook nhận tin nhắn từ WhatsApp Business Platform chính thức, một hàng đợi, chuyển giọng nói thành văn bản cho tin nhắn thoại, một LLM soạn câu trả lời bằng tiếng Ả Rập, và một bộ gửi trả lời trong khung 24 giờ của WhatsApp. Tin nhắn thoại quan trọng vì nhiều khách hàng nói tiếng Ả Rập thích nói bằng phương ngữ hơn là gõ chữ.
BroadRouter do BroadNet vận hành, nên các ví dụ dùng BroadNet Inference. Bất kỳ nhà cung cấp chuyển giọng nói thành văn bản và chat tương thích OpenAI nào cũng lắp vào cùng các vị trí đó.
Chatbot WhatsApp tiếng Ả Rập gồm những phần nào?
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. Bộ nhận webhook
WhatsApp Cloud API gửi tin nhắn đến dưới dạng request HTTPS POST tới webhook bạn đăng ký. Hai quy tắc giữ phần này khỏe mạnh:
- Xác minh mọi request. Tài liệu của Meta nói hãy tính HMAC-SHA256 của payload JSON bằng app secret và so sánh với header
X-Hub-Signature-256. Từ chối mọi thứ không khớp. - Trả về 200 thật nhanh. Lưu sự kiện và xác nhận nó. Đừng tải âm thanh hay gọi LLM bên trong handler webhook. Nếu gửi thất bại, Meta thử lại “immediately, then a few more times with decreasing frequency over the next 7 days” (bản dịch: ngay lập tức, rồi thêm vài lần nữa với tần suất giảm dần trong 7 ngày tiếp theo), và yêu cầu bạn tự xử lý chống trùng lặp.
Dùng message id của WhatsApp làm idempotency key, để một webhook được gửi lại không bao giờ tạo ra hai câu trả lời.
2. Hàng đợi
Hàng đợi tách thời điểm WhatsApp gửi tin khỏi thời gian xử lý của bạn. Nó cũng cho phép giới hạn số việc chạy đồng thời cho khớp với giới hạn inference. Key trả theo mức dùng của BroadNet cho phép 30 request mỗi phút và 4 request cùng lúc, nên một nhóm worker nhỏ có thử lại khi gặp 429 là cấu trúc phù hợp. Xem lỗi và thử lại và cách xử lý giới hạn 429.
3. Worker: từ tin nhắn thoại thành văn bản
Với tin nhắn thoại, webhook cho bạn một object audio có media id, một mime_type như audio/ogg; codecs=opus, và voice: true với bản ghi âm tạo trong WhatsApp. Worker gửi GET tới media id để lấy URL tải, tải file bằng access token của bạn, rồi chuyển đổi và chép lời. Endpoint của BroadNet nhận WAV hoặc MP3, nên hãy chuyển đổi trước:
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
Thư mục tạm biến mất sau lời gọi, giúp âm thanh không nằm lại trên ổ đĩa của bạn. Hướng dẫn tin nhắn thoại WhatsApp có phiên bản xử lý hàng loạt cho các cuộc chat đã xuất, và hướng dẫn chuyển giọng nói tiếng Ả Rập thành văn bản nói về định dạng và giới hạn. File phải nhỏ hơn 26.214.400 byte (25 MiB); tin nhắn thoại thông thường nhỏ hơn thế rất nhiều.
3b. Worker: soạn câu trả lời
Xử lý bản chép lời đúng như một tin nhắn được gõ, nhưng hãy báo cho model biết nó đến từ giọng nói, vì bản chép lời không có dấu câu và có thể chứa lỗi nhận dạng:
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
Để định tuyến, hãy yêu cầu model trả về structured output (intent, handover, reply) thay vì văn bản tự do, và hành động theo các trường; công cụ tạo JSON schema miễn phí viết schema từ một câu trả lời mẫu. Trong các bài test của BroadNet, Qwen3.8 27B hiểu phương ngữ vùng Vịnh và Ai Cập và viết tiếng Ả Rập trôi chảy; DeepSeek V4.1 Flash rẻ hơn tính theo token và là model trong các gói không giới hạn của BroadNet. Cả hai đều suy luận trước khi trả lời, nên hãy chừa chỗ trong max_tokens. Xử lý phương ngữ được nói kỹ trong tiếng Ả Rập vùng Vịnh, Ai Cập và Levant với LLM.
4. Bộ gửi
Câu trả lời đi ra qua endpoint messages của Cloud API cho phone number id của bạn. Gửi văn bản thuần cho các câu trả lời hội thoại. Định dạng của WhatsApp (in đậm, danh sách) hiển thị được, nhưng bảng và tiêu đề Markdown thì không, nên hãy dặn model đừng tạo ra chúng.
5. Lưu trữ
Giữ trạng thái hội thoại (mười lượt gần nhất là đủ cho hầu hết bot hỗ trợ), trạng thái opt-in của khách hàng và nhật ký kiểm tra ghi lại bot đã gửi gì và vì sao. Đừng lưu nhiều hơn mức cần: bản chép lời tin nhắn thoại thường chứa tên, địa chỉ và thông tin sức khỏe.
Những quy tắc chính sách WhatsApp nào áp dụng cho chatbot?
WhatsApp rất nghiêm ngặt về cách doanh nghiệp sử dụng nền tảng, và các quy tắc bảo vệ số điện thoại của bạn không kém gì khách hàng. Hãy đọc WhatsApp Business Messaging Policy trước khi ra mắt. Trên thực tế:
- Opt-in trước. Chính sách chỉ cho phép bạn liên hệ những người đã đưa số của họ cho bạn và đồng ý nhận tin từ bạn trên WhatsApp. Việc khách hàng nhắn cho bạn không phải là đồng ý nhận tiếp thị.
- Không gửi tin nhắn không được yêu cầu. Chính sách viết: “Do not confuse, deceive, defraud, mislead, spam, or surprise people with your communications.” (bản dịch: Đừng làm người khác bối rối, lừa dối, lừa đảo, gây hiểu lầm, gửi spam hay khiến họ bất ngờ bằng các liên lạc của bạn.) Không bao giờ gửi tin nhắn đầu tiên cho người chưa liên hệ với bạn hoặc chưa opt-in.
- Tôn trọng khung giờ chăm sóc khách hàng 24 giờ. Câu trả lời tự do được phép trong vòng 24 giờ kể từ tin nhắn cuối của khách. Ngoài khung đó, bạn chỉ được gửi các mẫu tin nhắn đã được duyệt.
- Cung cấp người thật. Trả lời tự động được phép trong khung 24 giờ, nhưng chính sách yêu cầu “prompt, clear, and direct escalation paths” (bản dịch: các đường chuyển tiếp nhanh chóng, rõ ràng và trực tiếp) tới một người.
- Tôn trọng yêu cầu dừng nhận tin. Chính sách nói bạn phải tôn trọng mọi yêu cầu chặn, ngừng hoặc hủy nhận tin. Hãy coi “stop” hoặc “توقف” là một yêu cầu như vậy.
Còn một quy tắc nữa là của chúng tôi, không phải của Meta: giữ câu trả lời đầu tiên cho liên hệ mới thật đơn giản. Một câu trả lời ngắn, văn bản thuần, không có URL là an toàn nhất. Tin nhắn nhiều link từ một doanh nghiệp lạ trông như spam với người dùng, và họ có thể chặn và báo cáo bạn. Hãy chia sẻ link sau, khi khách hàng yêu cầu.
Vận hành bot WhatsApp tiếng Ả Rập tốn bao nhiêu?
Chuyển giọng nói thành văn bản tính phí theo phút âm thanh. Với BroadNet Transcribe Arabic:
| Khối lượng | Chi phí |
|---|---|
| Một phút tin nhắn thoại | $0.0042 |
| Một giờ tin nhắn thoại | $0.25 |
| 10.000 tin nhắn thoại dài 30 giây | $21.00 |
Câu trả lời của LLM tính phí theo token khi trả theo mức dùng: trên 1 triệu token, Qwen3.8 27B là $0.175 đầu vào và $2.17 đầu ra, còn DeepSeek V4.1 Flash là $0.175 đầu vào và $0.52 đầu ra. Một câu trả lời hỗ trợ kèm mười lượt lịch sử là vài nghìn token, kể cả suy luận, nên một câu trả lời tốn vài phần nghìn của mức giá trên 1 triệu token ở trên. Nhập khối lượng tin nhắn của bạn vào công cụ tính chi phí LLM API miễn phí để có con số hằng tháng. Nếu bot chạy DeepSeek V4.1 Flash cả ngày, hãy so sánh với gói Full Moon $60 trên trang bảng giá.
Giữ tin nhắn thoại riêng tư thế nào?
Tin nhắn thoại là một trong những loại dữ liệu cá nhân nhất mà doanh nghiệp xử lý. BroadNet Inference không lưu giữ âm thanh, prompt hay bản chép lời sau request (xem không lưu giữ dữ liệu), nhưng điều đó chỉ áp dụng cho bước inference. Hãy quyết định hàng đợi, log và cơ sở dữ liệu của bạn giữ bản chép lời bao lâu, và xóa file media sau khi xử lý.
Danh sách kiểm tra trước khi ra mắt
- Chữ ký webhook đã được xác minh, trả về 200 trước khi xử lý.
- Idempotency theo message id của WhatsApp.
- Tin nhắn thoại được chuyển sang WAV và chép lời với
language=ar. - Nhóm worker có kích thước khớp với giới hạn request, có backoff khi gặp 429.
- System prompt đặt phương ngữ, văn phong, độ dài và “không có link”.
- Đường chuyển sang người thật đã được test.
- Opt-in được ghi lại; không gửi tin không được yêu cầu; chỉ dùng mẫu ngoài khung 24 giờ.
- Bản chép lời được xóa theo lịch.
Nếu bạn chỉ cần biến tin nhắn thoại thành ticket thay vì một bot biết trả lời, chuyển tin nhắn thoại thành văn bản cho doanh nghiệp nói về pipeline đơn giản hơn đó.
