An Arabic WhatsApp chatbot needs five parts: a webhook that receives messages from the official WhatsApp Business Platform, a queue, speech to text for voice notes, an LLM that drafts replies in Arabic, and a sender that answers within WhatsApp’s 24-hour window. Voice notes matter because many Arabic-speaking customers speak in dialect rather than type.
BroadRouter is run by BroadNet, so the examples use BroadNet Inference. Any OpenAI-compatible speech-to-text and chat provider fits the same slots.
What are the parts of an Arabic WhatsApp chatbot?
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 receiver
The WhatsApp Cloud API delivers incoming messages as HTTPS POST requests to a webhook you register. Two rules keep this part healthy:
- Verify every request. Meta’s docs say to compute an HMAC-SHA256 of the JSON payload with your app secret and compare it with the
X-Hub-Signature-256header. Reject anything that does not match. - Return 200 fast. Store the event and acknowledge it. Do not download audio or call an LLM inside the webhook handler. If delivery fails, Meta retries “immediately, then a few more times with decreasing frequency over the next 7 days”, and tells you to handle deduplication.
Use the WhatsApp message id as an idempotency key, so a redelivered webhook never produces two replies.
2. Queue
A queue decouples WhatsApp’s delivery timing from your processing time. It also lets you cap concurrency to match your inference limits. A BroadNet pay-as-you-go key allows 30 requests a minute and 4 at once, so a small worker pool with retries on 429 is the right shape. See errors and retries and how to handle 429 rate limits.
3. Worker: voice notes to text
For a voice note the webhook gives you an audio object with a media id, a mime_type such as audio/ogg; codecs=opus, and voice: true for recordings made in WhatsApp. The worker GETs the media id to obtain the download URL, downloads the file with your access token, then converts and transcribes it. BroadNet’s endpoint accepts WAV or MP3, so convert first:
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
The temporary directory disappears after the call, which keeps audio off your disks. The WhatsApp voice-note guide has a batch version for exported chats, and the Arabic speech-to-text guide covers formats and limits. Files must stay under 26,214,400 bytes (25 MiB); ordinary voice notes are far below that.
3b. Worker: drafting the reply
Treat a transcript exactly like a typed message, but tell the model it came from speech, since transcripts have no punctuation and may contain recognition errors:
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
For routing, ask the model for structured output (intent, handover, reply) instead of free text, and act on the fields; the free JSON schema generator writes the schema from an example reply. In BroadNet’s tests Qwen3.8 27B understood Gulf and Egyptian dialects and wrote fluent Arabic; DeepSeek V4.1 Flash is cheaper per token and is the model on BroadNet’s unlimited plans. Both reason before answering, so leave room in max_tokens. Dialect handling is covered in depth in Gulf, Egyptian and Levantine Arabic with LLMs.
4. Sender
Replies go out through the Cloud API’s messages endpoint for your phone number id. Send plain text for conversational replies. WhatsApp formatting (bold, lists) renders, but Markdown tables and headings do not, so tell the model not to produce them.
5. Store
Keep conversation state (last ten turns is plenty for most support bots), the customer’s opt-in status and an audit log of what the bot sent and why. Do not store more than you need: transcripts of voice notes often contain names, addresses and health details.
Which WhatsApp policy rules apply to a chatbot?
WhatsApp is strict about how businesses use it, and the rules protect your number as much as your customers. Read the WhatsApp Business Messaging Policy before launch. In practice:
- Opt-in first. The policy lets you contact people only if they gave you their number and opted in to hear from you on WhatsApp. A customer writing to you is not consent to marketing.
- No unsolicited messages. The policy says: “Do not confuse, deceive, defraud, mislead, spam, or surprise people with your communications.” Never send first messages to people who have not contacted you or opted in.
- Respect the 24-hour customer service window. Free-form replies are allowed within 24 hours of the customer’s last message. Outside it, you may only send approved message templates.
- Offer a human. Automated replies are allowed within the 24-hour window, but the policy requires “prompt, clear, and direct escalation paths” to a person.
- Honour opt-outs. The policy says you must respect every request to block, discontinue or opt out. Treat “stop” or “توقف” as one.
One more rule is ours, not Meta’s: keep first replies to new contacts plain. A short, plain-text reply with no URLs is safest. Link-heavy messages from an unfamiliar business look like spam to users, who can block and report you. Share links later, when the customer asks for them.
What does an Arabic WhatsApp bot cost to run?
Speech to text is billed per audio minute. With BroadNet Transcribe Arabic:
| Volume | Cost |
|---|---|
| One minute of voice notes | $0.0042 |
| One hour of voice notes | $0.25 |
| 10,000 voice notes of 30 seconds | $21.00 |
LLM replies are billed per token on pay-as-you-go: per 1M tokens, Qwen3.8 27B is $0.175 input and $2.17 output, and DeepSeek V4.1 Flash is $0.175 input and $0.52 output. A support reply with ten turns of history is a few thousand tokens, reasoning included, so a single reply costs a few thousandths of the per-1M prices above. Put your message volume into the free LLM API cost calculator for a monthly figure. If the bot runs on DeepSeek V4.1 Flash all day, compare against the $60 Full Moon plan on the pricing page.
How do you keep voice notes private?
Voice notes are some of the most personal data a business handles. BroadNet Inference does not retain audio, prompts or transcripts after the request (see zero data retention), but that only covers the inference step. Decide how long your own queue, logs and database keep transcripts, and delete media files after processing.
Launch checklist
- Webhook signature verified, 200 returned before processing.
- Idempotency on WhatsApp message id.
- Voice notes converted to WAV and transcribed with
language=ar. - Worker pool sized to your rate limits, with backoff on 429.
- System prompt sets dialect, register, length and “no links”.
- Handover path to a human, tested.
- Opt-in recorded; no unsolicited sends; templates only outside the 24-hour window.
- Transcripts deleted on a schedule.
If you only need voice notes turned into tickets rather than a bot that replies, voice notes to text for business covers that simpler pipeline.
