Un chatbot WhatsApp in arabo ha bisogno di cinque parti: un webhook che riceve i messaggi dalla WhatsApp Business Platform ufficiale, una coda, lo speech-to-text per i vocali, un LLM che scrive le bozze di risposta in arabo e un mittente che risponde entro la finestra di 24 ore di WhatsApp. I vocali contano perché molti clienti arabofoni parlano in dialetto invece di scrivere.
BroadRouter è gestito da BroadNet, quindi gli esempi usano BroadNet Inference. Qualsiasi fornitore di speech-to-text e chat compatibile con OpenAI si inserisce negli stessi punti.
Quali sono le parti di un chatbot WhatsApp in arabo?
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. Ricevitore del webhook
La WhatsApp Cloud API consegna i messaggi in arrivo come richieste HTTPS POST a un webhook che registri tu. Due regole mantengono sana questa parte:
- Verifica ogni richiesta. La documentazione di Meta dice di calcolare un HMAC-SHA256 del payload JSON con l’app secret e di confrontarlo con l’header
X-Hub-Signature-256. Rifiuta tutto ciò che non corrisponde. - Restituisci 200 subito. Salva l’evento e conferma la ricezione. Non scaricare audio e non chiamare un LLM dentro l’handler del webhook. Se la consegna fallisce, Meta riprova «immediately, then a few more times with decreasing frequency over the next 7 days» (traduzione: subito, poi ancora qualche volta con frequenza decrescente nei 7 giorni successivi) e ti chiede di gestire la deduplicazione.
Usa l’id del messaggio WhatsApp come chiave di idempotenza, così un webhook consegnato di nuovo non produce mai due risposte.
2. Coda
Una coda separa i tempi di consegna di WhatsApp dai tuoi tempi di elaborazione. Ti permette anche di limitare la concorrenza in base ai tuoi limiti di inferenza. Una chiave BroadNet a consumo consente 30 richieste al minuto e 4 in contemporanea, quindi la forma giusta è un piccolo pool di worker con nuovi tentativi sui 429. Vedi errori e nuovi tentativi e come gestire i rate limit 429.
3. Worker: dai vocali al testo
Per un vocale il webhook ti dà un oggetto audio con un id del media, un mime_type come audio/ogg; codecs=opus e voice: true per le registrazioni fatte in WhatsApp. Il worker fa una GET sull’id del media per ottenere l’URL di download, scarica il file con il tuo access token, poi lo converte e lo trascrive. L’endpoint di BroadNet accetta WAV o MP3, quindi prima converti:
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
La directory temporanea sparisce dopo la chiamata, così l’audio non resta sui tuoi dischi. La guida ai vocali WhatsApp ha una versione batch per le chat esportate, e la guida speech-to-text per l’arabo tratta formati e limiti. I file devono restare sotto i 26.214.400 byte (25 MiB); i normali vocali sono molto al di sotto.
3b. Worker: scrivere la risposta
Tratta una trascrizione esattamente come un messaggio scritto, ma di’ al modello che viene dal parlato, perché le trascrizioni non hanno punteggiatura e possono contenere errori di riconoscimento:
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
Per l’instradamento, chiedi al modello un output strutturato (intent, handover, reply) invece di testo libero e agisci sui campi; il generatore gratuito di JSON schema scrive lo schema partendo da una risposta di esempio. Nei test di BroadNet Qwen3.8 27B ha capito i dialetti del Golfo ed egiziano e ha scritto un arabo scorrevole; DeepSeek V4.1 Flash costa meno per token ed è il modello dei piani illimitati di BroadNet. Entrambi ragionano prima di rispondere, quindi lascia margine in max_tokens. La gestione dei dialetti è approfondita in arabo del Golfo, egiziano e levantino con gli LLM.
4. Mittente
Le risposte escono tramite l’endpoint messages della Cloud API per il tuo phone number id. Per le risposte di conversazione invia testo semplice. La formattazione di WhatsApp (grassetto, elenchi) viene visualizzata, ma tabelle e titoli Markdown no, quindi di’ al modello di non produrli.
5. Archivio
Conserva lo stato della conversazione (gli ultimi dieci turni bastano per la maggior parte dei bot di assistenza), lo stato del consenso del cliente e un log di audit di cosa ha inviato il bot e perché. Non conservare più del necessario: le trascrizioni dei vocali contengono spesso nomi, indirizzi e dati sulla salute.
Quali regole della policy WhatsApp valgono per un chatbot?
WhatsApp è severo su come le aziende lo usano, e le regole proteggono il tuo numero tanto quanto i tuoi clienti. Leggi la WhatsApp Business Messaging Policy prima del lancio. In pratica:
- Prima il consenso. La policy ti permette di contattare le persone solo se ti hanno dato il loro numero e hanno accettato di ricevere tuoi messaggi su WhatsApp. Un cliente che ti scrive non sta dando il consenso al marketing.
- Nessun messaggio non richiesto. La policy dice: «Do not confuse, deceive, defraud, mislead, spam, or surprise people with your communications.» (traduzione: non confondere, ingannare, frodare, fuorviare, spammare o sorprendere le persone con le tue comunicazioni). Non inviare mai primi messaggi a chi non ti ha contattato o non ha dato il consenso.
- Rispetta la finestra di assistenza clienti di 24 ore. Le risposte libere sono consentite entro 24 ore dall’ultimo messaggio del cliente. Fuori da quella finestra puoi inviare solo template di messaggio approvati.
- Offri una persona. Le risposte automatiche sono consentite entro la finestra di 24 ore, ma la policy richiede «prompt, clear, and direct escalation paths» (traduzione: percorsi di escalation rapidi, chiari e diretti) verso una persona.
- Rispetta le disiscrizioni. La policy dice che devi rispettare ogni richiesta di blocco, interruzione o opt-out. Tratta “stop” o “توقف” come tale.
Un’altra regola è nostra, non di Meta: tieni semplici le prime risposte ai nuovi contatti. Una risposta breve, in testo semplice e senza URL è la scelta più sicura. Messaggi pieni di link da un’azienda sconosciuta sembrano spam agli utenti, che possono bloccarti e segnalarti. Condividi i link più avanti, quando è il cliente a chiederli.
Quanto costa far funzionare un bot WhatsApp in arabo?
Lo speech-to-text si paga per minuto di audio. Con BroadNet Transcribe Arabic:
| Volume | Costo |
|---|---|
| Un minuto di vocali | $0.0042 |
| Un’ora di vocali | $0.25 |
| 10.000 vocali da 30 secondi | $21.00 |
Le risposte dell’LLM si pagano per token con il pagamento a consumo: per 1M di token, Qwen3.8 27B costa $0.175 di input e $2.17 di output, e DeepSeek V4.1 Flash $0.175 di input e $0.52 di output. Una risposta di assistenza con dieci turni di cronologia vale qualche migliaio di token, ragionamento compreso, quindi una singola risposta costa qualche millesimo dei prezzi per 1M indicati sopra. Inserisci il tuo volume di messaggi nel calcolatore gratuito dei costi delle API LLM per una cifra mensile. Se il bot gira tutto il giorno su DeepSeek V4.1 Flash, confrontalo con il piano Full Moon da $60 nella pagina prezzi.
Come si tengono privati i vocali?
I vocali sono tra i dati più personali che un’azienda gestisce. BroadNet Inference non conserva audio, prompt o trascrizioni dopo la richiesta (vedi zero data retention), ma questo copre solo il passaggio di inferenza. Decidi per quanto tempo la tua coda, i tuoi log e il tuo database conservano le trascrizioni, ed elimina i file media dopo l’elaborazione.
Checklist per il lancio
- Firma del webhook verificata, 200 restituito prima dell’elaborazione.
- Idempotenza sull’id del messaggio WhatsApp.
- Vocali convertiti in WAV e trascritti con
language=ar. - Pool di worker dimensionato sui tuoi rate limit, con backoff sui 429.
- Il system prompt fissa dialetto, registro, lunghezza e “niente link”.
- Passaggio a un operatore umano, testato.
- Consenso registrato; nessun invio non richiesto; solo template fuori dalla finestra di 24 ore.
- Trascrizioni eliminate a scadenza.
Se ti serve solo trasformare i vocali in ticket, invece di un bot che risponde, dai vocali al testo per le aziende descrive quella pipeline più semplice.
