Арабскому чат-боту в WhatsApp нужны пять частей: вебхук, принимающий сообщения от официальной WhatsApp Business Platform, очередь, распознавание речи для голосовых сообщений, LLM, которая готовит ответы на арабском, и отправитель, отвечающий в пределах 24-часового окна WhatsApp. Голосовые сообщения важны, потому что многие арабоязычные клиенты не печатают, а говорят — на диалекте.
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. Приёмник вебхуков
WhatsApp Cloud API доставляет входящие сообщения HTTPS-запросами POST на зарегистрированный вами вебхук. Два правила держат эту часть в порядке:
- Проверяйте каждый запрос. Документация Meta предписывает вычислять HMAC-SHA256 от JSON-тела с секретом приложения и сравнивать его с заголовком
X-Hub-Signature-256. Отклоняйте всё, что не совпадает. - Быстро возвращайте 200. Сохраните событие и подтвердите его. Не скачивайте аудио и не вызывайте LLM внутри обработчика вебхука. Если доставка не удалась, Meta повторяет её “immediately, then a few more times with decreasing frequency over the next 7 days” (перевод: «сразу, затем ещё несколько раз со снижающейся частотой в течение следующих 7 дней») и просит вас самим обрабатывать дубли.
Используйте id сообщения WhatsApp как ключ идемпотентности, чтобы повторно доставленный вебхук никогда не порождал два ответа.
2. Очередь
Очередь отвязывает время доставки WhatsApp от времени вашей обработки. Она же позволяет ограничить параллелизм под ваши лимиты инференса. Ключ BroadNet с оплатой по мере использования допускает 30 запросов в минуту и 4 одновременно, поэтому правильная схема — небольшой пул воркеров с повторами при 429. См. руководство об ошибках и повторах и статью о том, как обрабатывать лимиты 429.
3. Воркер: голосовые сообщения в текст
Для голосового сообщения вебхук передаёт объект audio с id медиафайла, mime_type вроде audio/ogg; codecs=opus и voice: true для записей, сделанных в WhatsApp. Воркер делает GET по id медиафайла, чтобы получить 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 МиБ); обычные голосовые сообщения намного меньше.
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. Отправитель
Ответы уходят через эндпоинт messages в Cloud API для id вашего номера телефона. Для разговорных ответов отправляйте простой текст. Форматирование WhatsApp (жирный, списки) отображается, а таблицы и заголовки Markdown — нет, поэтому скажите модели их не создавать.
5. Хранилище
Храните состояние разговора (последних десяти реплик хватает большинству ботов поддержки), статус согласия клиента и журнал аудита: что бот отправил и почему. Не храните больше, чем нужно: расшифровки голосовых часто содержат имена, адреса и сведения о здоровье.
Какие правила WhatsApp действуют для чат-бота?
WhatsApp строго следит за тем, как компании его используют, и эти правила защищают ваш номер не меньше, чем клиентов. Перед запуском прочитайте WhatsApp Business Messaging Policy. На практике:
- Сначала согласие. Политика разрешает связываться с людьми, только если они дали вам свой номер и согласились получать от вас сообщения в WhatsApp. То, что клиент вам написал, не означает согласия на маркетинг.
- Никаких незапрошенных сообщений. В политике сказано: “Do not confuse, deceive, defraud, mislead, spam, or surprise people with your communications.” (перевод: «Не запутывайте, не обманывайте, не вводите в заблуждение, не рассылайте спам и не застигайте людей врасплох своими сообщениями».) Никогда не отправляйте первые сообщения людям, которые с вами не связывались и не давали согласия.
- Соблюдайте 24-часовое окно обслуживания клиентов. Ответы в свободной форме разрешены в течение 24 часов после последнего сообщения клиента. За его пределами можно отправлять только одобренные шаблоны сообщений.
- Предлагайте человека. Автоматические ответы в 24-часовом окне разрешены, но политика требует “prompt, clear, and direct escalation paths” (перевод: «быстрых, понятных и прямых путей эскалации») к человеку.
- Выполняйте отписки. Политика требует уважать каждую просьбу заблокировать, прекратить рассылку или отписаться. Считайте такой просьбой и “stop”, и “توقف”.
Ещё одно правило наше, а не Meta: первые ответы новым контактам делайте простыми. Безопаснее всего короткий ответ простым текстом без URL. Сообщения, набитые ссылками, от незнакомой компании выглядят для пользователей как спам, а они могут вас заблокировать и пожаловаться. Делитесь ссылками позже, когда клиент о них попросит.
Сколько стоит работа арабского бота в WhatsApp?
Распознавание речи тарифицируется поминутно. С BroadNet Transcribe Arabic:
| Объём | Стоимость |
|---|---|
| Одна минута голосовых сообщений | $0.0042 |
| Один час голосовых сообщений | $0.25 |
| 10 000 голосовых сообщений по 30 секунд | $21.00 |
Ответы LLM при оплате по мере использования тарифицируются за токены: за 1 млн токенов Qwen3.8 27B стоит $0.175 за вход и $2.17 за выход, а DeepSeek V4.1 Flash — $0.175 за вход и $0.52 за выход. Ответ поддержки с десятью репликами истории — это несколько тысяч токенов вместе с рассуждениями, поэтому один ответ стоит несколько тысячных от указанных выше цен за 1 млн. Введите свой объём сообщений в бесплатный калькулятор стоимости LLM API, чтобы получить месячную сумму. Если бот целый день работает на DeepSeek V4.1 Flash, сравните с тарифом Full Moon за $60 на странице цен.
Как сохранить приватность голосовых сообщений?
Голосовые сообщения — одни из самых личных данных, с которыми работает компания. BroadNet Inference не хранит аудио, промпты и расшифровки после запроса (см. нулевое хранение данных), но это касается только шага инференса. Решите, сколько ваши собственные очередь, логи и база данных хранят расшифровки, и удаляйте медиафайлы после обработки.
Чек-лист запуска
- Подпись вебхука проверяется, 200 возвращается до обработки.
- Идемпотентность по id сообщения WhatsApp.
- Голосовые сообщения конвертируются в WAV и расшифровываются с
language=ar. - Пул воркеров рассчитан под ваши лимиты, с экспоненциальной задержкой при 429.
- Системный промпт задаёт диалект, регистр, длину и запрет ссылок.
- Путь передачи человеку есть и протестирован.
- Согласие зафиксировано; никаких незапрошенных отправок; вне 24-часового окна — только шаблоны.
- Расшифровки удаляются по расписанию.
Если вам нужно лишь превращать голосовые сообщения в тикеты, а не бот, который отвечает, этот более простой пайплайн описан в статье о голосовых сообщениях в текст для бизнеса.
