يحتاج بوت واتساب العربي إلى خمسة أجزاء: webhook يستقبل الرسائل من منصة WhatsApp Business Platform الرسمية، وطابور، وتحويل الكلام إلى نص للرسائل الصوتية، ونموذج LLM يصوغ الردود بالعربية، ومُرسِل يجيب داخل نافذة الـ 24 ساعة في واتساب. للرسائل الصوتية أهمية خاصة، لأن كثيرًا من العملاء الناطقين بالعربية يتكلمون بلهجتهم بدل أن يكتبوا.
يدير BroadNet موقع BroadRouter، لذا تستخدم الأمثلة BroadNet Inference. وأي مزوّد متوافق مع OpenAI لتحويل الكلام إلى نص وللمحادثة يصلح للمواضع نفسها.
ما أجزاء بوت واتساب العربي؟
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 الرسائل الواردة على شكل طلبات HTTPS POST إلى webhook تسجّله أنت. قاعدتان تحافظان على سلامة هذا الجزء:
- تحقّق من كل طلب. توصي وثائق Meta بحساب HMAC-SHA256 لمحتوى JSON باستخدام السرّ الخاص بتطبيقك (app secret)، ومقارنته بالترويسة
X-Hub-Signature-256. ارفض كل ما لا يطابق. - أعِد 200 بسرعة. خزّن الحدث وأكّد استلامه. لا تنزّل الصوت ولا تستدعِ LLM داخل معالج الـ webhook. إذا فشل التسليم، تعيد Meta المحاولة “immediately, then a few more times with decreasing frequency over the next 7 days” (الترجمة: «فورًا، ثم بضع مرات أخرى بوتيرة متناقصة خلال الأيام السبعة التالية»)، وتطلب منك معالجة التكرار بنفسك.
استخدم معرّف رسالة واتساب مفتاحًا لعدم التكرار (idempotency key)، حتى لا يُنتج webhook أُعيد تسليمه ردّين أبدًا.
2. الطابور
يفصل الطابور توقيت تسليم واتساب عن وقت المعالجة لديك. ويتيح لك أيضًا تحديد التزامن بما يوافق حدود الاستدلال. يسمح مفتاح الدفع حسب الاستخدام من BroadNet بـ 30 طلبًا في الدقيقة و4 في آنٍ واحد، لذا فالشكل المناسب مجموعة عمّال صغيرة تعيد المحاولة عند 429. راجع الأخطاء وإعادة المحاولة وكيف تعالج أخطاء حد المعدل 429.
3. العامل: من الرسائل الصوتية إلى نص
مع الرسالة الصوتية يعطيك الـ webhook كائن audio فيه id للوسائط، وmime_type مثل audio/ogg; codecs=opus، وvoice: true للتسجيلات المُنشأة داخل واتساب. يرسل العامل طلب GET بمعرّف الوسائط للحصول على رابط التنزيل، وينزّل الملف برمز الوصول (access token) الخاص بك، ثم يحوّله ويفرّغه. نقطة نهاية 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
يختفي المجلد المؤقت بعد الاستدعاء، فلا يبقى الصوت على أقراصك. يتضمن دليل تفريغ رسائل واتساب الصوتية نسخة دفعية للمحادثات المُصدَّرة، ويشرح دليل تحويل الكلام العربي إلى نص الصيغ والحدود. يجب أن يبقى حجم الملف أقل من 26,214,400 بايت (25 MiB)؛ والرسائل الصوتية العادية أصغر من ذلك بكثير.
3ب. العامل: صياغة الرد
تعامل مع النص المفرّغ كما تتعامل مع رسالة مكتوبة تمامًا، لكن أخبر النموذج أنه جاء من كلام منطوق، لأن النصوص المفرّغة بلا علامات ترقيم وقد تحتوي أخطاء في التعرّف:
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 Schema المجاني المخطط من مثال لرد. في اختبارات BroadNet فهم Qwen3.8 27B اللهجتين الخليجية والمصرية وكتب عربية سلسة؛ أما DeepSeek V4.1 Flash فأرخص لكل رمز (توكن) وهو النموذج المستخدم في خطط BroadNet غير المحدودة. كلاهما يُجري استدلالًا منطقيًا قبل الإجابة، فاترك هامشًا في max_tokens. وتجد معالجة اللهجات بالتفصيل في العربية الخليجية والمصرية والشامية مع نماذج LLM.
4. المُرسِل
تخرج الردود عبر نقطة نهاية الرسائل في Cloud API لمعرّف رقم هاتفك (phone number id). أرسل نصًا عاديًا للردود الحوارية. تنسيق واتساب (الخط العريض والقوائم) يظهر بشكل صحيح، أما جداول Markdown والعناوين فلا، لذا اطلب من النموذج ألا يُنتجها.
5. التخزين
احتفظ بحالة المحادثة (آخر عشر رسائل تكفي معظم بوتات الدعم)، وحالة موافقة العميل على التواصل، وسجل تدقيق لما أرسله البوت ولماذا. لا تخزّن أكثر مما تحتاج: فالنصوص المفرّغة من الرسائل الصوتية تحتوي غالبًا أسماء وعناوين وتفاصيل صحية.
ما قواعد سياسة واتساب التي تنطبق على البوت؟
واتساب صارم في طريقة استخدام الشركات له، وقواعده تحمي رقمك بقدر ما تحمي عملاءك. اقرأ سياسة WhatsApp Business للمراسلة قبل الإطلاق. عمليًا:
- الموافقة أولًا. تسمح السياسة بالتواصل مع الأشخاص فقط إذا أعطوك رقمهم ووافقوا على تلقي رسائلك عبر واتساب. وكون العميل راسلك لا يعني موافقته على الرسائل التسويقية.
- لا رسائل غير مطلوبة. تقول السياسة: “Do not confuse, deceive, defraud, mislead, spam, or surprise people with your communications.” (الترجمة: «لا تُربك الناس أو تخدعهم أو تحتال عليهم أو تضللهم أو تُغرقهم برسائل مزعجة أو تفاجئهم برسائلك».) لا ترسل أبدًا رسائل أولى إلى أشخاص لم يتواصلوا معك ولم يوافقوا على التواصل.
- التزم بنافذة خدمة العملاء البالغة 24 ساعة. الردود الحرة مسموحة خلال 24 ساعة من آخر رسالة للعميل. وخارجها لا يجوز لك إلا إرسال قوالب رسائل معتمدة.
- وفّر موظفًا بشريًا. الردود الآلية مسموحة داخل نافذة الـ 24 ساعة، لكن السياسة تشترط “prompt, clear, and direct escalation paths” (الترجمة: «مسارات تصعيد سريعة وواضحة ومباشرة») إلى شخص حقيقي.
- احترم طلبات إلغاء الاشتراك. تقول السياسة إن عليك احترام كل طلب بالحظر أو الإيقاف أو إلغاء الاشتراك. اعتبر “stop” أو «توقف» طلبًا من هذا النوع.
وهناك قاعدة أخرى من عندنا، لا من Meta: اجعل الردود الأولى على جهات الاتصال الجديدة بسيطة. الرد القصير بنص عادي وبلا روابط هو الأكثر أمانًا. الرسائل المليئة بالروابط من نشاط تجاري غير مألوف تبدو للمستخدمين رسائل مزعجة، ويمكنهم حظرك والإبلاغ عنك. شارك الروابط لاحقًا، حين يطلبها العميل.
كم يكلّف تشغيل بوت واتساب عربي؟
يُحتسب تحويل الكلام إلى نص لكل دقيقة صوت. مع BroadNet Transcribe Arabic:
| الحجم | التكلفة |
|---|---|
| دقيقة واحدة من الرسائل الصوتية | $0.0042 |
| ساعة واحدة من الرسائل الصوتية | $0.25 |
| 10,000 رسالة صوتية مدة كل منها 30 ثانية | $21.00 |
تُحتسب ردود LLM لكل رمز في الدفع حسب الاستخدام: لكل مليون رمز، سعر Qwen3.8 27B هو $0.175 للإدخال و$2.17 للإخراج، وسعر DeepSeek V4.1 Flash هو $0.175 للإدخال و$0.52 للإخراج. رد الدعم مع عشر رسائل من السجل يبلغ بضعة آلاف من الرموز، بما فيها الاستدلال المنطقي، لذا فالرد الواحد يكلّف بضعة أجزاء من الألف من أسعار المليون رمز أعلاه. أدخل حجم رسائلك في حاسبة تكلفة LLM API المجانية لتحصل على رقم شهري. وإذا كان البوت يعمل على DeepSeek V4.1 Flash طوال اليوم، فقارن ذلك بخطة البدر (Full Moon) بسعر $60 في صفحة الأسعار.
كيف تحافظ على خصوصية الرسائل الصوتية؟
الرسائل الصوتية من أكثر البيانات الشخصية حساسية التي يتعامل معها أي نشاط تجاري. لا تحتفظ BroadNet Inference بالصوت أو الأوامر أو النصوص المفرّغة بعد الطلب (راجع عدم الاحتفاظ بالبيانات)، لكن ذلك يغطي خطوة الاستدلال فقط. حدّد كم من الوقت يحتفظ طابورك وسجلاتك وقاعدة بياناتك بالنصوص المفرّغة، واحذف ملفات الوسائط بعد المعالجة.
قائمة التحقق قبل الإطلاق
- التحقق من توقيع الـ webhook، وإعادة 200 قبل المعالجة.
- عدم التكرار (idempotency) بالاعتماد على معرّف رسالة واتساب.
- تحويل الرسائل الصوتية إلى WAV وتفريغها مع
language=ar. - حجم مجموعة العمّال مضبوط على حدود المعدل، مع انتظار متزايد عند 429.
- الأمر النظامي (system prompt) يحدد اللهجة والأسلوب والطول و«بلا روابط».
- مسار تحويل إلى موظف بشري، تم اختباره.
- تسجيل الموافقة على التواصل؛ لا إرسال غير مطلوب؛ قوالب فقط خارج نافذة الـ 24 ساعة.
- حذف النصوص المفرّغة وفق جدول زمني.
إذا كنت تحتاج فقط إلى تحويل الرسائل الصوتية إلى تذاكر دعم بدل بوت يرد، فمقال تحويل الرسائل الصوتية إلى نص للأعمال يشرح هذا المسار الأبسط.
