アラビア語の WhatsApp チャットボットには 5 つの部分が必要です。公式の WhatsApp Business Platform からメッセージを受け取る Webhook、キュー、ボイスメッセージ用の音声認識、アラビア語で返信を起草する 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. Webhook 受信部
WhatsApp Cloud API は、受信メッセージを、登録した Webhook への HTTPS POST リクエストとして配信します。この部分を健全に保つルールは 2 つです。
- **すべてのリクエストを検証する。**Meta のドキュメントでは、アプリシークレットで JSON ペイロードの HMAC-SHA256 を計算し、
X-Hub-Signature-256ヘッダーと比較するよう求めています。一致しないものはすべて拒否します。 - **すぐに 200 を返す。**イベントを保存して受信を確認します。Webhook ハンドラー内で音声をダウンロードしたり LLM を呼び出したりしないでください。配信に失敗すると、Meta は “immediately, then a few more times with decreasing frequency over the next 7 days”(訳:すぐに、その後 7 日間にわたり頻度を下げながら数回)再試行し、重複排除は自分で処理するよう求めています。
WhatsApp のメッセージ ID を冪等性キーとして使えば、再配信された Webhook で返信が 2 回送られることはありません。
2. キュー
キューは、WhatsApp の配信タイミングと自社の処理時間を切り離します。推論の制限に合わせて同時実行数を抑えることもできます。BroadNet の従量課金キーでは毎分 30 リクエスト、同時に 4 件まで送れるため、429 で再試行する小さなワーカープールが適した形です。エラーと再試行と 429 レート制限への対処法を参照してください。
3. ワーカー:ボイスメッセージをテキストに
ボイスメッセージの場合、Webhook からは audio オブジェクトが届きます。メディアの id、audio/ogg; codecs=opus のような mime_type、そして WhatsApp で録音されたものには voice: true が含まれます。ワーカーはメディア 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. ワーカー:返信の起草
書き起こしは入力されたメッセージとまったく同じように扱いますが、音声由来であることをモデルに伝えてください。書き起こしには句読点がなく、認識誤りを含むことがあるためです。
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 ビジネスメッセージングポリシーを読んでください。実際には次のとおりです。
- **まずオプトイン。**ポリシーで連絡が認められているのは、番号を提供し、WhatsApp で連絡を受け取ることにオプトインした人だけです。顧客からメッセージが来たことは、マーケティングへの同意ではありません。
- **迷惑メッセージは送らない。**ポリシーには “Do not confuse, deceive, defraud, mislead, spam, or surprise people with your communications.”(訳:コミュニケーションで人を混乱させたり、だましたり、詐取したり、誤解させたり、スパムを送ったり、驚かせたりしないでください)とあります。連絡してきていない人やオプトインしていない人に、最初のメッセージを送ってはいけません。
- **24 時間のカスタマーサービスウィンドウを守る。**顧客の最後のメッセージから 24 時間以内なら、自由形式の返信が認められます。それ以外では、承認済みのメッセージテンプレートしか送れません。
- **人による対応を用意する。**24 時間ウィンドウ内の自動返信は認められていますが、ポリシーは人への “prompt, clear, and direct escalation paths”(訳:迅速で明確かつ直接的なエスカレーション経路)を求めています。
- **オプトアウトを尊重する。**ポリシーでは、ブロック、停止、オプトアウトのすべての要求を尊重する必要があります。「stop」や「توقف」もその 1 つとして扱ってください。
もう 1 つは Meta ではなく私たちのルールです。**新しい連絡先への最初の返信はシンプルに。**URL を含まない短いプレーンテキストの返信が最も安全です。見知らぬ企業からのリンクだらけのメッセージは、ユーザーにはスパムに見え、ブロックや報告をされかねません。リンクは、顧客が求めたときに後で共有してください。
アラビア語 WhatsApp ボットの運用コストは?
音声認識は音声 1 分単位で課金されます。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 ターン付きのサポート返信は推論を含めて数千トークンなので、1 件の返信の費用は上記の 100 万トークンあたり料金の 1,000 分の数程度です。月額の目安は、メッセージ量を無料の LLM API コスト計算ツールに入力して求めてください。ボットが一日中 DeepSeek V4.1 Flash で動くなら、料金ページの $60 の Full Moon プランと比較してください。
ボイスメッセージのプライバシーはどう守りますか?
ボイスメッセージは、企業が扱うデータの中でも特に個人的なものです。BroadNet Inference はリクエスト後に音声、プロンプト、書き起こしを保持しません(ゼロデータ保持を参照)が、それが対象とするのは推論のステップだけです。自社のキュー、ログ、データベースが書き起こしをどれだけ保持するかを決め、処理後はメディアファイルを削除してください。
公開前チェックリスト
- Webhook の署名を検証し、処理の前に 200 を返している。
- WhatsApp のメッセージ ID で冪等性を確保している。
- ボイスメッセージを WAV に変換し、
language=arで文字起こししている。 - ワーカープールのサイズがレート制限に合っており、429 でバックオフする。
- システムプロンプトで方言、文体、長さ、「リンクなし」を指定している。
- 有人対応への引き継ぎ経路をテスト済み。
- オプトインを記録している。迷惑メッセージは送らない。24 時間ウィンドウ外ではテンプレートのみ。
- 書き起こしを定期的に削除している。
返信するボットではなく、ボイスメッセージをチケットにするだけでよい場合は、ビジネス向けボイスメッセージの文字起こしで、より簡単なパイプラインを紹介しています。
