إعداد أحداث Webhooks

مدونة واتساب للأعمال

اشترك في أحداث Webhooks للحصول على إشعارات حول الرسائل التي يتلقاها نشاطك التجاري وتحديثات الملف الشخصي للعميل.

إنشاء نقطة نهاية

قبل أن تتمكن من تلقي الإشعارات، ستحتاج إلى إنشاء نقطة نهاية على الخادم لديك لتلقي الإشعارات.

يجب أن تكون نقطة النهاية قادرة على معالجة نوعين من طلبات HTTPS وهما: طلبات التحقق وإشعارات الأحداث. نظرًا إلى أن كلا الطلبين يستخدم بروتوكولات HTTP، يجب أن يتوفر لدى خادمك شهادة TLS أو SSL صالحة تم تكوينها وتثبيتها بشكل صحيح. علمًا بأن الشهادات الموقّعة ذاتيًا غير مدعومة.

التعرف على المزيد حول طلبات التحقق وإشعارات الأحداث

لن يؤثر إعداد أحداث Webhooks على رقم الهاتف المسجل في تطبيق واتساب للأعمال. ولن تتمكن من استخدام رقمك المسجل في تطبيق واتساب للأعمال فقط في حالة ترحيل رقمك إلى منصة واتساب للأعمال.

الاشتراك في أحداث Webhooks

للاشتراك في أحداث Webhooks، ستحتاج إلى الحصول على معرف تطبيق Meta والأذونات. ولإجراء ذلك، انتقل إلى لوحة معلومات تطبيق Meta. وهناك ستقوم بما يلي:

  1. إنشاء تطبيق من النوع "أعمال" في لوحة معلومات تطبيق Meta
  2. إضافة منتج Webhooks إلى تطبيق Meta في لوحة معلومات التطبيق

    يمكن لكل تطبيق Meta تكوين نقطة نهاية واحدة فقط في أي وقت. إذا كنت تحتاج إلى إرسال تحديثات webhook إلى عدة نقاط نهاية، فستحتاج إلى عدة تطبيقات Meta.

إذا كنت شريك حلول، فقد تحتاج إلى ما يلي:

  1. إضافة الإذن whatsapp_business_messaging في لوحة معلومات التطبيق
  2. إكمال مراجعة التطبيقات من Meta بنجاح – ستستغرق هذه الخطوة بعض الوقت، ولكن يمكنك الاستمرار في الاختبار أثناء عملية المراجعة بأكملها.

فهم أحداث Webhooks

عند وقوع حدث تشغيل، تعرض منصة واتساب للأعمال الحدث وترسل على الفور إشعارًا إلى عنوان URL الذي حددته مسبقًا. يمكنك الحصول على نوعين من الإشعارات وهما:

  • الرسائل المستلمة: يخبرك هذا التنبيه بمجرد استلام رسالة جديدة. كما يمكن أن تجدها تحت مسمى "الإشعارات الواردة" في باقي الوثائق.
  • إشعارات التسعير وحالة الرسالة: يخبرك هذا التنبيه عند تغيير حالة الرسالة —على سبيل المثال، تمت قراءة الرسالة أو تم تسليمها. كما يمكن أن تجدها تحت مسمى "الإشعارات الصادرة" في باقي الوثائق.

تحتوي كل أحداث Webhooks على التنسيق العام التالي:

{
  "object": "whatsapp_business_account",
  "entry": [{
      "id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
      "changes": [{
          "value": {
              "messaging_product": "whatsapp",
              "metadata": {
                  "display_phone_number": "PHONE_NUMBER",
                  "phone_number_id": "PHONE_NUMBER_ID"
              },
              # specific Webhooks payload            
          },
          "field": "messages"
        }]
    }]
}

راجع المكونات للحصول على معلومات حول كل حقل.

إذا تلقيت رسالة غير مدعومة في API السحابة، فستحصل على حدث webhook لرسالة غير معروفة.

حجم حمولة البيانات

يمكن أن تصل حمولات بيانات أحداث Webhooks إلى 3 ميجابايت.

عينة من نقاط نهاية التطبيق

أنشئ عينة من نقطة نهاية التطبيق لاختبار أحداث webhooks.

فشل تسليم حدث Webhook

إذا أرسلت طلب حدث webhook إلى نقطة النهاية واستجاب الخادم برمز حالة HTTP بخلاف 200، أو إذا تعذر علينا تسليم حدث webhook لأي سبب أخر، فسنستمر في محاولة تقليل معدل التكرار حتى ينجح الطلب، لما يصل إلى 7 أيام.

لاحظ أنه سيتم إرسال عمليات إعادة المحاولة إلى كل التطبيقات التي اشتركت في أحداث webhooks (والحقول الملائمة) في حساب واتساب للأعمال. قد يؤدي هذا إلى تكرار إشعارات webhook.

عناوين IP

يمكنك الحصول على عناوين IP لخوادم webhook من خلال تشغيل الأمر التالي في الوحدة الطرفية:

whois -h whois.radb.net — '-i origin AS32934' | grep ^route | awk '{print $2}' | sort

بشكل دوري نعمل على تغيير عناوين IP هذه، لذلك إذا كنت تدرج خوادمنا في قائمة السماح، فقد ترغب في إعادة إنشاء هذه القائمة من حين لآخر وتحديث قائمة السماح وفقًا لذلك.

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

تعرف على المزيد حول المعلومات التي يمكنك تلقيها في إشعار Webhooks.