إعداد واجهة WhatsApp Business API
في هذا الدليل ستتعلم خطوة بخطوة كيفية ربط WhatsApp Business Cloud API مع BitPalm.
إنشاء Meta Business Portfolio وتفعيل المصادقة الثنائية
إذا لم يكن لديك حساب بعد، أنشئ Meta Business Portfolio و حساب Facebook Developer.
يجب أن يكون حساب المطور مرتبطاً بـ Business Portfolio الخاص بك.
مهم: فعّل المصادقة الثنائية
منذ 2025 ترفض Meta أي وصول إلى Cloud API إذا لم تكن المصادقة الثنائية (2FA) مفعّلة في Business Portfolio. فعّل المصادقة الثنائية قبل أي شيء آخر، وإلا سيفشل الإعداد لاحقاً بدون رسالة خطأ واضحة. اذهب إلى Business Portfolio ← مركز الأمان ← المصادقة الثنائية.
تطبيق جديد في Meta App Dashboard
اذهب إلى developers.facebook.com/apps وانقر على "إنشاء تطبيق".
- اختر حالة الاستخدام "Connect with customers through WhatsApp"
- اختر اسماً للتطبيق (مثلاً "شركتي واتساب بوت") وبريدك الإلكتروني التجاري
- اختر Business Portfolio (أو أنشئ واحداً)
هذه هي حالة الاستخدام الصحيحة منذ تحديث Meta لعام 2025. النوع "Business" القديم لا يزال يظهر، لكنه يتعطل في عدة أماكن أثناء إعداد WhatsApp.
التحقق من إضافة منتج WhatsApp
إذا اخترت حالة الاستخدام الصحيحة في الخطوة 2، فإن منتج WhatsApp مُضاف تلقائياً. وإلا، انقر على "إضافة منتجات" في القائمة الجانبية واختر "WhatsApp".
ثم اتبع معالج Quickstart. سينقلك مباشرة إلى منطقة API Setup، حيث تتم الخطوات التالية.
اختبر بالرقم التجريبي، ثم سجّل رقمك الخاص
تحت WhatsApp > API Setup ستجد رقم هاتف تجريبي مجاني. معرّف رقم الهاتف يظهر مباشرة أسفله.
الرقم التجريبي يعمل فقط مع 5 مستلمين محددين مسبقاً. هو موجود لكي تختبر الإعداد الكامل قبل الانتقال إلى البث المباشر.
للاستخدام الفعلي: سجّل رقم هاتفك الخاص
في نفس صفحة API Setup، انقر على "Add phone number" وأدخل رقم عملك الحقيقي. ترسل Meta رمز تأكيد عبر SMS أو مكالمة. بعدها يجب أن تحدد رمز PIN مكوّن من 6 أرقام للتحقق بخطوتين للرقم. بدون هذا الـ PIN ستفشل أي إعادة تسجيل لاحقاً. سجّل الـ PIN في مكان آمن، لن تحتاجه كثيراً، لكنه إلزامي عند إعادة التسجيل.
يجب ألّا يكون الرقم مسجّلاً في تطبيق WhatsApp على جهاز في نفس الوقت. إذا كان كذلك، سجّل خروج هناك أولاً أو احذف الرقم من تطبيق WhatsApp. إذا كان العميل يريد الاستمرار في استخدام تطبيق WhatsApp Business بالتوازي، راجع ملاحظة Coexistence أدناه.
Coexistence: الاستمرار في استخدام تطبيق WhatsApp Business بالتوازي
منذ مايو 2025، تسمح Meta برقم واحد يعمل في تطبيق WhatsApp Business وفي Cloud API في نفس الوقت. تتم مزامنة المحادثات بين الاثنين (حتى 6 أشهر من السجل عند الربط الأول). مفيد للعملاء الذين يريدون أن يستمر موظفوهم في الدردشة عبر الهاتف، بينما يتولى BitPalm الردود الآلية وجمع العملاء المحتملين بالتوازي.
مهم: تعمل Coexistence فقط عبر تدفق Embedded Signup، وليس عبر الإعداد اليدوي الموضّح في هذا الدليل. تقوم BitPalm حالياً بتقييم Embedded Signup، أخبرنا إذا كنت بحاجة إليه. Coexistence غير متاحة حالياً في الاتحاد الأوروبي والمملكة المتحدة وأستراليا واليابان ونيجيريا والفلبين وروسيا وكوريا الجنوبية وجنوب أفريقيا وتركيا. لكنها تعمل في الإمارات ومعظم الأسواق الأخرى. حد المعدل: 5 رسائل في الثانية، يكفي لمعظم حالات الاستخدام الواردة.
إنشاء رمز وصول دائم
الرمز المؤقت في صفحة إعداد API ينتهي بعد 24 ساعة وغير مناسب للإنتاج. للحصول على رمز دائم:
- اذهب إلى Business Settings ← Users ← System Users
- أنشئ مستخدم نظام جديد بصلاحية مسؤول (يمثّل تكاملك، وليس شخصاً)
- على مستخدم النظام، انقر على "Add Assets" وعيّن حساب WhatsApp والتطبيق مع Full Control
- ثم انقر على "Generate New Token"
- اختر تطبيقك وهذه الصلاحيات بالضبط: whatsapp_business_messaging & whatsapp_business_management
خطوة تعيين الـ Assets هي الأكثر تفويتاً. إذا تم إنشاء الرمز بنجاح ولكن فشل الإرسال لاحقاً بخطأ "insufficient permissions"، فإن هذه الخطوة هي السبب في معظم الأحيان.
اختيار رمز التحقق
رمز التحقق هو أي نص تحدده بنفسك. يُستخدم للتحقق من الـ Webhook.
اختر نصاً آمناً وعشوائياً. يجب أن يكون متطابقاً في بوابة Meta ولوحة تحكم BitPalm.
إعداد رابط Webhook
اذهب إلى WhatsApp > Configuration > Webhook وأدخل الرابط التالي:
أدخل نفس قيمة رمز التحقق من الخطوة 6.
الاشتراك في حقول Webhook
بعد التحقق من Webhook، تحتاج للاشتراك في الحقول المناسبة. انقر على "Webhook fields" وفعّل: "Manage":
هذا يتيح لـ BitPalm استقبال رسائل واتساب الواردة من عملائك.
العثور على معرّف WABA (اختياري)
معرّف حساب WhatsApp Business (WABA ID) مطلوب إذا كنت تريد مزامنة وإرسال قوالب الرسائل. إذا كنت تحتاج فقط إلى الرسائل النصية الأساسية، يمكنك تخطي هذه الخطوة.
- افتح Meta Business Suite ← حسابات واتساب
- اختر حساب WhatsApp Business الخاص بك من القائمة.
- يُعرض معرّف WABA في شريط العنوان وفي صفحة نظرة عامة على الحساب. إنه معرّف رقمي.
يمكنك أيضاً العثور عليه في بوابة Meta Developer تحت تطبيقك ← WhatsApp ← API Setup ← WhatsApp Business Account ID.
الإدخال في لوحة التحكم والاختبار
افتح لوحة تحكم BitPalm، انتقل إلى Channels > WhatsApp وأدخل:
- معرّف رقم الهاتف من الخطوة 4
- رمز الوصول من الخطوة 5
- رمز التحقق من الخطوة 6
- معرّف WABA (اختياري) من الخطوة 9
انقر على "حفظ" وأرسل رسالة تجريبية إلى رقم واتساب الخاص بك. يجب أن يظهر رد وكيلك خلال ثوانٍ قليلة.
ما الذي تتقاضاه ميتا مقابل الرسائل
تعمل واجهة WhatsApp Business API عبر فوترة ميتا، وليس BitPalm. غيّرت ميتا نموذج التسعير اعتباراً من 1 يوليو 2025: ابتعاداً عن الفوترة القديمة المعتمدة على المحادثة، وانتقالاً إلى أسعار لكل رسالة قالب مُسلَّمة. رسائل الخدمة (الردود على المحادثات التي يبدأها الزائر خلال 24 ساعة) مجانية تماماً، بلا حصة وبلا حد أقصى. تُفرض رسوم على رسائل التسويق والمرافق والمصادقة لكل رسالة. يعتمد السعر الدقيق على بلد المستلم. تختلف الأسعار حوالي 10 أضعاف بين الأسواق المنخفضة التكلفة مثل الهند أو البرازيل والأسواق المتميزة مثل الإمارات والمملكة المتحدة وألمانيا والولايات المتحدة.
رسائل الخدمة (الزائر يكتب أولاً)
عندما يرسل الزائر رسالة إلى البوت أولاً ويرد البوت خلال نافذة 24 ساعة. هذا ما سيشكل حوالي 95٪ من حركة المرور لديك.
مجانية تماماً. لا حصة، لا حد أقصى.
رسائل التسويق (أنت تكتب أولاً)
قوالب ترويجية معتمدة مسبقًا تبدأها أنت (إعادة التواصل، العروض، الإعلانات). هذه هي الفئة الأغلى. تتطلب القوالب مراجعة من ميتا تستغرق 24 إلى 48 ساعة.
رسائل المرافق (Utility)
قوالب معاملات (تحديثات الطلب، تذكيرات المواعيد، تنبيهات الحساب). أرخص من التسويق.
رسائل المصادقة
رموز OTP وتسجيل الدخول. أقل سعر مدفوع، مصمم لحالات استخدام كلمة المرور لمرة واحدة.
تتم الفوترة عبر بطاقة الائتمان في حساب Meta Business الخاص بك. الفوترة شهرية. راجع صفحة أسعار WhatsApp الرسمية للحصول على الأسعار الحالية حسب البلد ولتقدير تكلفتك الشهرية.
لا تضيف BitPalm أي هامش ربح على تكاليف WhatsApp من ميتا. ما تفوتره ميتا، تدفعه أنت.
التحقق من الأعمال: متى يصبح ضرورياً
يبدأ الرقم المسجّل حديثاً في الفئة الأولى بحد 1,000 محادثة لكل 24 ساعة. طالما بقيت تحت هذا الحد، لا تحتاج إلى تحقق رسمي من Meta. عندما تتجاوزه بانتظام، أو عندما ترغب في اعتماد اسم العرض الخاص بك (بدلاً من الاسم العام)، تطلب Meta تحققاً من الأعمال (Business Verification) برخصة تجارية أو سجل تجاري أو ما يعادله في بلدك. تتم المراجعة عبر Meta وتستغرق عادة بضعة أيام. من الجيد معرفة ذلك قبل التوسع، لكنه ليس عائقاً للإطلاق.