BroadRouter

阿拉伯语 WhatsApp 聊天机器人架构:从语音消息到自动回复

BroadNet Inference 团队 · 阅读约 5 分钟 · 发布于 · 更新于

阿拉伯语 WhatsApp 助手由五部分组成:接收 WhatsApp Business Platform 消息的 webhook、队列、处理语音消息的语音转文字、起草回复的大模型,以及通过 API 回复的发送器。用 BroadNet Transcribe Arabic 转换并转写语音消息,每分钟音频 $0.0042。

一个阿拉伯语 WhatsApp 聊天机器人需要五个部分:接收官方 WhatsApp Business Platform 消息的 webhook、队列、处理语音消息的语音转文字、用阿拉伯语起草回复的大模型,以及在 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. Webhook 接收器

WhatsApp Cloud API 以 HTTPS POST 请求的形式,把收到的消息发送到你注册的 webhook。有两条规则能让这一部分保持健康:

  • **验证每一个请求。**Meta 的文档要求用你的应用密钥对 JSON 载荷计算 HMAC-SHA256,并与 X-Hub-Signature-256 请求头比对。不匹配的一律拒绝。
  • **尽快返回 200。**把事件存下来并确认。不要在 webhook 处理函数里下载音频或调用大模型。如果投递失败,Meta 会 “immediately, then a few more times with decreasing frequency over the next 7 days”(译文:立即重试,之后在接下来 7 天内以逐渐降低的频率再重试几次),并要求你自己处理去重。

用 WhatsApp 消息 id 作为幂等键,这样重复投递的 webhook 永远不会产生两条回复。

2. 队列

队列把 WhatsApp 的投递时机和你的处理时间解耦。它还让你可以限制并发,以匹配推理服务的限制。BroadNet 按量付费密钥每分钟允许 30 个请求,同时最多 4 个,所以一个遇到 429 会重试的小型 worker 池是合适的结构。参见错误与重试和如何处理 429 速率限制。

3. Worker:语音消息转文字

对于语音消息,webhook 会给你一个 audio 对象,其中包含媒体 id、audio/ogg; codecs=opus 这样的 mime_type,以及表示在 WhatsApp 中录制的 voice: true。Worker 用媒体 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 字节(25 MiB);普通语音消息远低于这个大小。

3b. Worker:起草回复

把转写文本当作打字消息一样处理,但要告诉模型它来自语音,因为转写文本没有标点,还可能有识别错误:

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 schema 生成器可以根据一条示例回复写出 schema。在 BroadNet 的测试中,Qwen3.8 27B 能理解海湾和埃及方言,并能写出流畅的阿拉伯语;DeepSeek V4.1 Flash 每 token 更便宜,也是 BroadNet 不限量套餐所用的模型。两者都会先思考再作答,所以要在 max_tokens 里留出空间。方言处理在用大模型处理海湾、埃及和黎凡特阿拉伯语中有深入介绍。

4. 发送器

回复通过 Cloud API 中你的电话号码 id 对应的 messages 端点发出。对话式回复用纯文本发送。WhatsApp 的格式(粗体、列表)能正常显示,但 Markdown 表格和标题不能,所以要告诉模型不要生成它们。

5. 存储

保存对话状态(对大多数客服机器人来说,最近十轮就足够了)、客户的选择接收状态,以及记录机器人发了什么、为什么发的审计日志。不要存储超出需要的内容:语音消息的转写文本经常包含姓名、地址和健康信息。

聊天机器人要遵守哪些 WhatsApp 政策规则?

WhatsApp 对企业的使用方式要求很严,这些规则保护你的号码,也保护你的客户。上线前请阅读 WhatsApp 商业消息政策。实际操作中:

  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:

用量 费用
一分钟语音消息 $0.0042
一小时语音消息 $0.25
10,000 条 30 秒的语音消息 $21.00

大模型回复在按量付费模式下按 token 计费:每百万 token,Qwen3.8 27B 输入 $0.175、输出 $2.17,DeepSeek V4.1 Flash 输入 $0.175、输出 $0.52。一条带十轮历史的客服回复(含思考)只有几千个 token,所以单条回复的费用只是上面每百万 token 价格的千分之几。把你的消息量填进免费的大模型 API 费用计算器,就能得到月度费用。如果机器人全天在 DeepSeek V4.1 Flash 上运行,可以和价格页面上 $60 的 Full Moon 套餐比较一下。

怎么保护语音消息的隐私?

语音消息是企业处理的最私密的数据之一。BroadNet Inference 在请求结束后不保留音频、提示词或转写文本(参见零数据保留),但这只覆盖推理这一步。你需要决定自己的队列、日志和数据库保留转写文本多久,并在处理完后删除媒体文件。

上线检查清单

  • 已验证 webhook 签名,处理之前先返回 200。
  • 以 WhatsApp 消息 id 实现幂等。
  • 语音消息已转换为 WAV,并用 language=ar 转写。
  • Worker 池大小与速率限制匹配,遇到 429 会退避。
  • 系统提示词设定了方言、语体、长度和“不带链接”。
  • 转人工的路径已经测试过。
  • 已记录同意状态;不发未经请求的消息;24 小时窗口之外只用模板。
  • 定期删除转写文本。

如果你只需要把语音消息变成工单,而不需要会回复的机器人,面向企业的语音消息转文字介绍了那条更简单的流水线。

常见问题

可以给从没联系过我的客户发消息吗?

只有在对方选择接收你企业的消息时才可以,而且只能用已审核通过的消息模板。未经请求的消息违反 WhatsApp 的政策,可能导致你的号码被限制。

为什么转写之前要先转换语音消息?

WhatsApp 语音消息是 Ogg/Opus 文件,而 BroadNet 的转写端点接受 WAV 或 MP3。一条 ffmpeg 命令就能把它们转成 16 kHz 单声道 WAV。

该用哪个大模型来起草回复?

用你自己的消息测试。BroadNet 报告,在其测试中 Qwen3.8 27B 能理解海湾和埃及方言,并能写出流畅的阿拉伯语;DeepSeek V4.1 Flash 每 token 更便宜,而且可以用固定价格套餐。

WhatsApp 机器人在多长时间内可以不用模板回复?

在客户最后一条消息之后的 24 小时客服窗口内,你可以发送自由格式的回复。窗口之外,WhatsApp 商业消息政策只允许发送已审核通过的消息模板。

WhatsApp 聊天机器人需要转人工吗?

需要。该政策允许自动化,但要求提供及时、清晰、直接的升级途径,比如在聊天中转给人工客服、电话号码、电子邮件或支持表单。

BroadNet 会保留语音消息吗?

不会。BroadNet Inference 只为该请求处理音频和转写文本,不予保留。你自己的服务器和 WhatsApp 仍然保存着副本,所以那边也要规划保留期限。

以 Markdown 格式阅读问 ChatGPT问 Claude问 Perplexity