كيفية إعداد واجهة برمجيات واتساب من ميتا (WhatsApp Meta API)

تواصل مع خادم ميتا (Meta) البرمجي الخلفي الرسمي لتوجيه حركة رسائل المعاملات الكبيرة مباشرة عبر قنوات واجهة برمجة التطبيقات السحابية الرسمية (Cloud API). يمكنك دمج واجهة برمجيات ميتا (Meta API) باستخدام إما طريقة الاتصال السريع (Quick Connect) المؤتمتة والجديدة (موصى بها) أو طريقة الإعداد اليدوي (Manual Setup) المتقدمة.

الطريقة أ: الاتصال السريع عبر فيسبوك (موصى به)

هذه هي الطريقة الأسهل والأسرع للاتصال. من خلال توفير معرف تطبيق ميتا (Meta App ID)، يمكنك تفويض Wawp لاسترداد رمز الوصول (Access Token)، ومعرف حساب واتساب للأعمال (WhatsApp Business Account ID)، ومعرف رقم الهاتف (Phone Number ID) تلقائياً، والاشتراك في الويب هوكس (Webhooks) الخاصة بك بشكل مؤتمت بالكامل.

الخطوة 1: إنشاء تطبيق واجهة برمجيات واتساب ميتا (WhatsApp Meta API App)

للبدء، يجب عليك تسجيل تطبيق مطور على منصة ميتا للحصول على معرف التطبيق (App ID) والمفتاح السري للتطبيق (App Secret):

1. ادخل إلى لوحة تحكم التطبيقات: تطبيقات فيسبوك للمطورين (FaceBook Developer apps)
2. انقر على زر إنشاء تطبيق (Create APP) لبدء سير العمل القياسي.

3. حدد حالات الاستخدام (Use cases) التي تتطابق مع قنوات الاتصال التجارية الخاصة بك. اختر أخرى (Other)، ثم حدد واتساب (WhatsApp).

4. قم بتخصيص معلمات ربط المؤسسة لربط كيانك بأمان.

5. أدخل اسم التطبيق (App Name) بدقة وبريد الإدارة الإلكتروني القياسي للتواصل (Contact E-Mail).

6. اربط التطبيق بصرامة بدليل حساب فيسبوك للأعمال (Facebook Business Account) المخصص لك.

7. ستظهر شاشة المراجعة النهائية. أكمل خطوات الإعداد الإلزامية لحفظ المتغيرات.

8. أدخل بيانات اعتماد حسابك للتحقق بشكل آمن وتفويض إتمام الإنشاء.

9. انسخ معرف التطبيق (App ID) والمفتاح السري للتطبيق (App Secret) من الشريط العلوي أو من تبويب إعدادات التطبيق > أساسي (App Settings > Basic) في لوحة تحكم مطوري ميتا الخاصة بك.

الخطوة 2: التهيئة والاتصال السريع في Wawp

بمجرد الحصول على معرف تطبيق ميتا (Meta App ID) والمفتاح السري للتطبيق (Meta App Secret)، يمكنك تفويض Wawp بنقرة واحدة:

1. انتقل إلى قسم إرسال عبر واجهة برمجيات ميتا (Meta API Sender) داخل لوحة تحكم Wawp الخاصة بك.

2. في حقلي معرف تطبيق ميتا (Meta App ID) والمفتاح السري لتطبيق ميتا (Meta App Secret)، الصق المفاتيح التي نسختها من فيسبوك، ثم انقر على حفظ (Save).
3. تحت شريط الاتصال السريع (Quick Connect)، انقر فوق زر الاتصال بواسطة فيسبوك (Connect with Facebook).
4. ستفتح نافذة منبثقة آمنة لتفويض فيسبوك (Facebook OAuth). قم بتسجيل الدخول إلى حساب فيسبوك الخاص بك وحدد حسابات واتساب للأعمال وأرقام الهواتف التي تريد منح Wawp حق الوصول إليها.
5. امنح الصلاحيات المطلوبة: whatsapp_business_management و whatsapp_business_messaging.
6. بمجرد تفويضه، سيستخدم Wawp تلقائياً واجهة برمجيات Graph API من ميتا لجلب:
   • رمز وصول دائم (Permanent Access Token) (يتم ملؤه تلقائياً في الإعدادات)
   • معرف حساب واتساب للأعمال (WABA ID) (يتم ملؤه تلقائياً)
   • معرف رقم الهاتف (Phone Number ID) (يتم ملؤه تلقائياً)
   • رمز التحقق (Verify Token) (يتم إنشاؤه تلقائياً كرمز عشوائي آمن)

الخطوة 3: الاشتراك في الويب هوكس (Webhooks) تلقائياً

مع حفظ المفتاح السري ومعرف التطبيق، يمكنك الاشتراك في الأحداث المباشرة في الوقت الفعلي تلقائياً ودون الحاجة لتكوين يدوي:

1. مرر لأسفل إلى بطاقة الأحداث الواردة (Webhook) في Wawp.
2. تأكد من وجود رمز التحقق (Verify Token) الخاص بك.
3. انقر على زر الاشتراك التلقائي (Subscribe Automatically). سيقوم Wawp تلقائياً بمخاطبة واجهة برمجيات Meta Graph API لتسجيل رابط معاودة الاتصال (callback URL) للويب هوك ورمز التحقق.
4. انقر فوق حفظ (Save) في Wawp.

خلف الكواليس: كيف يعمل الاتصال السريع (Quick Connect)؟

للمطورين المتقدمين، تقوم آلية الاتصال بواسطة فيسبوك (Connect with Facebook) بأتمتة عملية المصافحة بالكامل باستخدام حزم تطوير البرمجيات (SDK) الرسمية من ميتا وواجهات برمجة تطبيقات OAuth:

• 1. تكوين التطبيق وتهيئة حزمة SDK: عند حفظ معرف تطبيق ميتا الخاص بك، تقوم إضافة Wawp بتحميل وتهيئة حزمة تطوير برمجيات فيسبوك لجافا سكريبت (Facebook JavaScript SDK) الرسمية (FB.init()) في صفحة إدارة الووردبريس الخاصة بك.
• 2. تدفق تفويض OAuth: يؤدي النقر فوق الاتصال بواسطة فيسبوك إلى تشغيل دالة window.FB.login()، مما يفتح نافذة حوار آمنة من فيسبوك تطلب منك تفويض Wawp بصلاحيتين أساسيتين لواتساب:
  • whatsapp_business_management (لاكتشاف حساب واتساب للأعمال الخاص بك وتكوينه).
  • whatsapp_business_messaging (لإرسال رسائل المعاملات بأحجام ضخمة).
• 3. رمز الوصول وتوليد المفاتيح: بعد الموافقة، يعيد فيسبوك رمز وصول (Access Token) لـ OAuth إلى واجهة Wawp الأمامية، والتي تقوم بملء حقل رمز الوصول الدائم (Permanent Access Token). كما يقوم Wawp على الفور بتوليد سلسلة عشوائية آمنة كـ رمز تحقق (Verify Token).
• 4. الاكتشاف التلقائي للأعمال والهاتف: يستعلم Wawp من واجهة برمجيات Graph API لميتا (/me/whatsapp_business_accounts). ويسترد على الفور معرف حساب واتساب للأعمال (WABA ID) ورقم الهاتف المرتبط به (Phone Number ID)، ويملأ حقول الإعدادات تلقائياً.
• 5. اشتراك ويب هوك مؤتمت: عند النقر فوق الاشتراك التلقائي، يستدعي خادم Wawp الخلفي نقطة نهاية اشتراك التطبيقات في ميتا (/v17.0/{waba_id}/subscribed_apps) باستخدام رمز الوصول الخاص بك، ليربط ويب هوك موقعك بشكل آمن.

الطريقة ب: الإعداد اليدوي (إعداد احتياطي)

إذا كنت تفضل تكوين المعلمات يدوياً أو واجهت أي مشكلات في التفويض مع فيسبوك OAuth، يمكنك استخدام التكوين اليدوي التقليدي:

الخطوة 1: إنشاء تطبيق واجهة برمجيات واتساب ميتا (WhatsApp Meta API App)

اتبع نفس سير عمل إنشاء التطبيق الموضح في الطريقة أ - الخطوة 1 للحصول على تطبيق مطور ميتا الخاص بك.

الخطوة 2: تخصيص واتساب للحصول على المفاتيح

بمجرد إنشاء التطبيق، قم بتنشيط منتج واتساب وإنشاء بيانات الاعتماد يدوياً:

1. حدد موقع وحدة منتج واتساب (WhatsApp) ونشطها داخل لوحة تحكم التطبيق.

2. اربط الأصول المطلوبة عبر لوحات التحكم لتتطابق مع أهداف النشر المقصودة.

3. اختر نماذج الاشتراك (Opt-In) بعناية:

• الاشتراك للكل (Opt-In All): يمنح التطبيق إمكانية وصول ديناميكية كاملة إلى أي أرقام مسجلة عالمياً.
• الاشتراك للمحدد (Opt-In Selected): يقيد حدود التطبيق بأصول الأرقام المدرجة بدقة فقط.

4. احفظ التكوينات للاحتفاظ بالإعدادات التشغيلية.

5. قم بإنهاء وتوليد دفق بيانات اعتماد التفويض الديناميكي.

6. انسخ الرموز الدائمة التي تم إنشاؤها بأمان.

الخطوة 3: نقل المفاتيح إلى إضافة Wawp

قم بتوجيه مكونات المطور عبر لوحة تكوين Wawp لإنشاء جسر اتصال:

1. حدد موقع قسم إرسال عبر واجهة برمجيات ميتا (Meta API Sender) داخل Wawp.
2. الصق رمز التفويض المنسوخ مباشرة في حقل رمز الوصول الدائم (Permanent Access Token).

الخطوة 4: دمج معرفات الأعمال (Business Identifiers)

قم بمزامنة أرقام معرفات الهوية في الخلفية لتمكين منطق توجيه الرسائل الجماعية السحابية:

1. حدد موقع وانسخ معرف حساب واتساب للأعمال (WhatsApp Business Account ID) المميز ومعرف رقم الهاتف (Phone Number ID) الظاهرين داخل لوحة تحكم ميتا الخاصة بك.

2. انتقل إلى حقول الإدخال والصق معرف WABA ID ومعرف رقم الهاتف في حقولهما الخاصة داخل الإضافة.

3. انقر على حفظ (Save) في Wawp.

الخطوة 5: إعداد الويب هوكس الديناميكية (الطريقة اليدوية)

قم بمزامنة استدعاءات الحالة للسماح بالتحقق من تسليم الرسائل في الوقت الفعلي وتحديثات الإشعارات من الهواتف:

1. ادخل إلى لوحة التحكم المخصصة بصرامة لمعالجات الويب هوك (Webhook) في لوحة مطوري ميتا.

2. انسخ رابط نقطة النهاية (Rest Endpoint URL) المعروض تحت بطاقة الويب هوك في Wawp.

3. الصقه في نافذة تكوين ويب هوك ميتا تحت حقل رابط الاستدعاء (Callback URL)، وأدخل رمز التحقق (Verify Token) الخاص بـ Wawp تحت حقل رمز التحقق (Verify Token). تحقق من صحة الويب هوك واحفظه.

4. قم بتنشيط الاشتراكات المطلوبة لتحديد قنوات الأحداث النشطة. ضمن اشتراكات حقول الويب هوك، اشترك في messages لتلقي الإشعارات الواردة وحالات التسليم.

الخطوات التالية

الخطوة 6: مزامنة القوالب المعتمدة

يقوم Wawp بجلب وتخزين جميع قوالبك المعتمدة مسبقاً مؤقتاً لتتمكن من استخدامها داخل تدفقات العمل:

1. مرر لأسفل إلى قسم قوالب واتساب (WhatsApp Templates).
2. انقر فوق مزامنة الآن (Sync Now) لجلب الكتالوج من سحابة ميتا (Meta Cloud).

الخطوة 7: اختبار قنوات الإرسال الرسمية

تحقق من عمليات البث المباشر عبر وحدات إشعارات الإضافة الأصلية بعد الانتهاء من عملية الربط.

1. منشئ الإشعارات (Notifications Builder): أرسل حمولات اختبارية فورية.

2. الحملات الجماعية (Bulk Campaigns): تحقق من إرسال حملات الشرائح بكفاءة عالية.

3. استعادة السلات المتروكة (Cart Recovery): قم بإجراء فحص لمنطق استعادة السلة المؤتمت.

راقب متتبعات الاستجابة في الوقت الفعلي للتحقق من حالات نجاح الإرسال الصحيحة.

المراقبة واستكشاف الأخطاء وإصلاحها

بمجرد تشغيل واجهة برمجيات ميتا (Meta API) الخاصة بك، يمكنك مراقبة كل رسالة مرسلة وحالة تسليمها في الوقت الفعلي من خلال مركز نشاط Wawp (Wawp Activity Hub). (للمطورين المتقدمين، يمكنك استكشاف نقاط نهاية رسائل واجهة برمجيات Wawp للتكاملات المخصصة).