Um chatbot de WhatsApp em árabe precisa de cinco partes: um webhook que recebe as mensagens da WhatsApp Business Platform oficial, uma fila, fala para texto para os áudios, um LLM que redige as respostas em árabe e um remetente que responde dentro da janela de 24 horas do WhatsApp. Os áudios importam porque muitos clientes que falam árabe falam em dialeto em vez de digitar.
O BroadRouter é mantido pela BroadNet, então os exemplos usam a BroadNet Inference. Qualquer provedor de fala para texto e de chat compatível com a OpenAI se encaixa nos mesmos lugares.
Quais são as partes de um chatbot de WhatsApp em árabe?
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. Receptor do webhook
A WhatsApp Cloud API entrega as mensagens recebidas como requisições HTTPS POST para um webhook que você registra. Duas regras mantêm essa parte saudável:
- Verifique toda requisição. A documentação da Meta manda calcular um HMAC-SHA256 do payload JSON com o app secret e comparar com o header
X-Hub-Signature-256. Rejeite tudo o que não bater. - Retorne 200 rápido. Guarde o evento e confirme o recebimento. Não baixe áudio nem chame um LLM dentro do handler do webhook. Se a entrega falhar, a Meta tenta de novo “immediately, then a few more times with decreasing frequency over the next 7 days” (tradução: imediatamente, depois mais algumas vezes com frequência decrescente ao longo dos 7 dias seguintes) e pede que você trate a deduplicação.
Use o id da mensagem do WhatsApp como chave de idempotência, para que um webhook reentregue nunca gere duas respostas.
2. Fila
Uma fila separa o tempo de entrega do WhatsApp do seu tempo de processamento. Ela também permite limitar a concorrência de acordo com seus limites de inferência. Uma chave da BroadNet no pagamento por uso permite 30 requisições por minuto e 4 ao mesmo tempo, então o formato certo é um pequeno pool de workers com novas tentativas em 429. Veja erros e novas tentativas e como lidar com rate limits 429.
3. Worker: de áudios a texto
Para um áudio, o webhook entrega um objeto audio com um id de mídia, um mime_type como audio/ogg; codecs=opus e voice: true para gravações feitas no WhatsApp. O worker faz um GET no id da mídia para obter a URL de download, baixa o arquivo com seu access token e então converte e transcreve. O endpoint da BroadNet aceita WAV ou MP3, então converta antes:
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
O diretório temporário some depois da chamada, o que mantém o áudio fora dos seus discos. O guia de áudios do WhatsApp tem uma versão em lote para conversas exportadas, e o guia de fala para texto em árabe trata de formatos e limites. Os arquivos precisam ficar abaixo de 26.214.400 bytes (25 MiB); áudios comuns ficam muito abaixo disso.
3b. Worker: redigindo a resposta
Trate uma transcrição exatamente como uma mensagem digitada, mas avise o modelo de que ela veio da fala, já que transcrições não têm pontuação e podem conter erros de reconhecimento:
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
Para o roteamento, peça ao modelo saída estruturada (intent, handover, reply) em vez de texto livre e aja com base nos campos; o gerador gratuito de JSON schema escreve o schema a partir de uma resposta de exemplo. Nos testes da BroadNet, o Qwen3.8 27B entendeu os dialetos do Golfo e egípcio e escreveu árabe fluente; o DeepSeek V4.1 Flash é mais barato por token e é o modelo dos planos ilimitados da BroadNet. Os dois raciocinam antes de responder, então deixe folga em max_tokens. O tratamento de dialetos é aprofundado em árabe do Golfo, egípcio e levantino com LLMs.
4. Remetente
As respostas saem pelo endpoint de mensagens da Cloud API para o seu phone number id. Envie texto simples nas respostas de conversa. A formatação do WhatsApp (negrito, listas) aparece, mas tabelas e títulos em Markdown não, então diga ao modelo para não gerá-los.
5. Armazenamento
Guarde o estado da conversa (os últimos dez turnos bastam para a maioria dos bots de suporte), o status de opt-in do cliente e um log de auditoria do que o bot enviou e por quê. Não guarde mais do que precisa: transcrições de áudios muitas vezes contêm nomes, endereços e dados de saúde.
Quais regras de política do WhatsApp valem para um chatbot?
O WhatsApp é rígido com o uso que as empresas fazem dele, e as regras protegem seu número tanto quanto seus clientes. Leia a WhatsApp Business Messaging Policy antes do lançamento. Na prática:
- Opt-in primeiro. A política só permite contatar pessoas que deram o número a você e aceitaram receber suas mensagens no WhatsApp. Um cliente que escreve para você não está consentindo com marketing.
- Nada de mensagens não solicitadas. A política diz: “Do not confuse, deceive, defraud, mislead, spam, or surprise people with your communications.” (tradução: não confunda, engane, fraude, induza ao erro, faça spam nem surpreenda as pessoas com suas comunicações). Nunca envie primeiras mensagens a quem não entrou em contato com você nem deu opt-in.
- Respeite a janela de atendimento ao cliente de 24 horas. Respostas livres são permitidas até 24 horas depois da última mensagem do cliente. Fora dela, só é possível enviar templates de mensagem aprovados.
- Ofereça um humano. Respostas automáticas são permitidas dentro da janela de 24 horas, mas a política exige “prompt, clear, and direct escalation paths” (tradução: caminhos de escalonamento rápidos, claros e diretos) até uma pessoa.
- Respeite os opt-outs. A política diz que você deve atender a todo pedido de bloqueio, interrupção ou opt-out. Trate “stop” ou “توقف” como um deles.
Mais uma regra é nossa, não da Meta: mantenha simples as primeiras respostas a contatos novos. Uma resposta curta, em texto simples e sem URLs, é o mais seguro. Mensagens cheias de links vindas de uma empresa desconhecida parecem spam para o usuário, que pode bloquear e denunciar você. Mande links depois, quando o cliente pedir.
Quanto custa manter um bot de WhatsApp em árabe?
Fala para texto é cobrada por minuto de áudio. Com o BroadNet Transcribe Arabic:
| Volume | Custo |
|---|---|
| Um minuto de áudios | $0.0042 |
| Uma hora de áudios | $0.25 |
| 10.000 áudios de 30 segundos | $21.00 |
As respostas do LLM são cobradas por token no pagamento por uso: por 1M de tokens, o Qwen3.8 27B custa $0.175 de input e $2.17 de output, e o DeepSeek V4.1 Flash $0.175 de input e $0.52 de output. Uma resposta de suporte com dez turnos de histórico tem alguns milhares de tokens, com o raciocínio incluído, então uma única resposta custa alguns milésimos dos preços por 1M acima. Coloque seu volume de mensagens na calculadora gratuita de custo de API de LLM para ter um valor mensal. Se o bot roda no DeepSeek V4.1 Flash o dia inteiro, compare com o plano Full Moon de $60 na página de preços.
Como manter os áudios privados?
Áudios estão entre os dados mais pessoais que uma empresa trata. A BroadNet Inference não retém áudio, prompts nem transcrições após a requisição (veja retenção zero de dados), mas isso só cobre a etapa de inferência. Decida por quanto tempo sua fila, seus logs e seu banco de dados guardam as transcrições, e apague os arquivos de mídia depois do processamento.
Checklist de lançamento
- Assinatura do webhook verificada, 200 retornado antes do processamento.
- Idempotência pelo id da mensagem do WhatsApp.
- Áudios convertidos para WAV e transcritos com
language=ar. - Pool de workers dimensionado para seus rate limits, com backoff em 429.
- O system prompt define dialeto, registro, tamanho e “sem links”.
- Caminho de transferência para um humano, testado.
- Opt-in registrado; nenhum envio não solicitado; só templates fora da janela de 24 horas.
- Transcrições apagadas em uma rotina programada.
Se você só precisa transformar áudios em tickets, e não de um bot que responde, áudios para texto nas empresas cobre esse pipeline mais simples.
