أحداث Webhooks من Meta لمنصة Messenger

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

لتنفيذ أحداث Webhooks بنجاح في محادثات Messenger أو Instagram، ستحتاج إلى ما يلي:

1. إنشاء نقطة نهاية على الخادم لتلقي إشعارات Webhooks وكائنات JSON ومعالجتها
2. تكوين منتج Webhooks من Meta في لوحة معلومات التطبيق
3. الاشتراك في إشعارات Webhooks من Meta التي تريد تلقيها
4. تثبيت تطبيق المراسلة على صفحة فيسبوك المرتبطة بالنشاط التجاري أو بحساب Instagram الاحترافي

قبل البدء

قبل البدء، سنفترض أنك قمت بما يلي:

• قراءة وتنفيذ المكونات المطلوبة للتطوير من خلال Meta في نظرة عامة على منصة Messenger

تكوين خادم Node.JS

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

توضح الأقسام أدناه المحتويات التي سيتضمنها كل نوع من أنواع الطلبات وكيفية الاستجابة لها.

عينات الرمز المعروضة هنا مأخوذة من عينة التطبيق المتواجد في GitHub . ويمكنك زيارة GitHub للاطلاع على المثال الكامل والمزيد من المعلومات حول إعداد خادم webhooks.

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

لإنشاء نقطة نهاية لتلقي إشعارات أحداث webhooks من منصة Messenger، قد يبدو ملف app.js كما يلي:

// Create the endpoint for your webhook

app.post("/webhook", (req, res) => {
  let body = req.body;

  console.log(`\u{1F7EA} Received webhook:`);
  console.dir(body, { depth: null });
    
...
   

يُستخدم هذا الرمز لإنشاء نقطة نهاية /webhook تقبل طلبات POST ويتحقق من أن الطلب يمثل إشعار webhook.

إرجاع الاستجابة 200 OK

يجب أن تُرجع نقطة النهاية الاستجابة 200 OK، والتي تخبر منصة Messenger بأن الحدث قد تم استلامه ولا يجب إعادة إرساله. وبطبيعة الحال، لن ترسل هذه الاستجابة إلا بعد الانتهاء من معالجة الإشعار.

الاستجابة لإشعارات الحدث

يجب أن تستجيب نقطة النهاية لديك لكل الإشعارات:

• من خلال الاستجابة 200 OK HTTPS
• في غضون 5 ثوانٍ أو أقل

سيكون الرمز التالي في app.post ضمن ملف app.js وقد يبدو كما يلي:

...
  // Send a 200 OK response if this is a page webhook

  if (body.object === "page") {
    // Returns a '200 OK' response to all requests
    res.status(200).send("EVENT_RECEIVED");
...
    // Determine which webhooks were triggered and get sender PSIDs and locale, message content and more.
...
  } else {
    // Return a '404 Not Found' if event is not from a page subscription
    res.sendStatus(404);
  }
}); 

طلبات التحقق

عندما تقوم في أي وقت بتكوين منتج Webhooks في لوحة معلومات التطبيق لديك، سنرسل طلب GET إلى عنوان URL الخاص بنقطة النهاية. تتضمن طلبات التأكيد معلمات سلسلة الاستعلام التالية، ويتم إلحاقها بنهاية عنوان URL الخاص بنقطة النهاية. ستبدو كما يلي:

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

GET https://www.your-clever-domain-name.com/webhooks? hub.mode=subscribe& hub.verify_token=mytoken& hub.challenge=1158201444

التحقق من صحة طلبات التحقق

عندما تتلقى نقطة النهاية لديك طلب تحقق، يجب أن:

• يتحقق من مطابقة القيمة hub.verify_token مع السلسلة التي قمت بتعيينها في الحقل رمز التحقق عندما تقوم بتكوين منتج Webhooks في لوحة معلومات التطبيق لديك (لم تقم بإعداد سلسلة الرمز هذه حتى الآن).
• تستجيب بالقيمة hub.challenge.

قد يبدو ملف app.js كما يلي:

// Add support for GET requests to our webhook
app.get("/messaging-webhook", (req, res) => {
  
// Parse the query params
  let mode = req.query["hub.mode"];
  let token = req.query["hub.verify_token"];
  let challenge = req.query["hub.challenge"];

  // Check if a token and mode is in the query string of the request
  if (mode && token) {
    // Check the mode and token sent is correct
    if (mode === "subscribe" && token === config.verifyToken) {
      // Respond with the challenge token from the request
      console.log("WEBHOOK_VERIFIED");
      res.status(200).send(challenge);
    } else {
      // Respond with '403 Forbidden' if verify tokens do not match
      res.sendStatus(403);
    }
  }
});

ملاحظة: تحول لغة PHP النقاط (.) إلى شرطات سفلية (_) في أسماء المعلمات .

إذا كنت موجودًا في لوحة معلومات التطبيق لديك وتقوم بتكوين منتج Webhooks (وبالتالي، تشغيل طلب التحقق)، فستشير لوحة المعلومات إلى ما إذا كانت نقطة النهاية قد تحققت من صحة الطلب بشكل صحيح. وإذا كنت تستخدم نقطة نهاية /app/subscriptions في واجهة Graph API لتكوين منتج أحداث Webhooks، فسترجع API استجابة بالنجاح أو الفشل.

إشعارات الأحداث

عند تكوين منتج Webhooks لديك، ستشترك في fields محددة بالنوع object (مثل، الحقل messages لدى الكائن page). وعندما يطرأ تغيير على أحد هذه الحقول، سنرسل إلى نقطة النهاية طلب POST يتضمن حمولة بيانات JSON يوضح التغيير.

على سبيل المثال، إذا اشتركت في حقل message_reactions للكائن page وتفاعل العميل مع رسالة أرسلها تطبيقك، فسنرسل لك طلب POST سيبدو كما يلي:

{
  "object":"page",
  "entry":[
    {
      "id":"<PAGE_ID>",
      "time":1458692752478,
      "messaging":[
        {
          "sender":{
            "id":"<PSID>"
          },
          "recipient":{
            "id":"<PAGE_ID>"
          },

          ...
        }
      ]
    }
  ]
}

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

ستتضمن حمولات البيانات كائنًا يوضح التغيير. وعند تكوين منتج webhooks، يمكنك الإشارة إلى ما إذا كان يجب أن تتضمن حمولات البيانات أسماء الحقول التي تم تغييرها فقط أو إذا كانت يجب أن تتضمن القيم الجديدة أيضًا.

وسنقوم بتنسيق كل حمولات البيانات بلغة JSON بحيث يمكنك تحليل حمولة البيانات باستخدام تنسيق لغة JSON الشائع الذي يحلل الأساليب أو الحِزم.

التحقق من حمولات البيانات

نوقع كل حمولات بيانات "إشعار الحدث" بتوقيع SHA256، ونقوم بتضمين التوقيع في عنوان "X-Hub-Signature-256" الخاص بالطلب المسبوق بالتوقيع "sha256=". لا يتعين عليك التحقق من صحة حمولة البيانات، ولكن يُفضل إجراء ذلك ونوصي بشدة بذلك.

للتحقق من صحة حمولة البيانات:

1. أنشئ توقيع SHA256 باستخدام حمولة البيانات والمفتاح السري للتطبيق في تطبيقك.
2. قارن توقيعك بالتوقيع الموجود في عنوان X-Hub-Signature-256 (كل ما يأتي بعد sha256=). في حالة مطابقة التواقيع، تكون حمولة البيانات حقيقية.

قد يبدو ملف app.js كما يلي:

// Import dependencies and set up http server
const express = require("express"),
  bodyParser = require("body-parser"),
  { urlencoded, json } = require("body-parser"),
  app = express().use(bodyParser.json());
    
    ...


// Verify that the callback came from Facebook.
function verifyRequestSignature(req, res, buf) {
  var signature = req.headers["x-hub-signature-256"];

  if (!signature) {
    console.warn(`Couldn't find "x-hub-signature-256" in headers.`);
  } else {
    var elements = signature.split("=");
    var signatureHash = elements[1];
    var expectedHash = crypto
      .createHmac("sha256", config.appSecret)
      .update(buf)
      .digest("hex");
    if (signatureHash != expectedHash) {
      throw new Error("Couldn't validate the request signature.");
    }
  }
}

إعادة محاولة تسليم أحداث Webhooks

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

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

اختبار أحداث Webhooks

لاختبار التحقق من حدث webhook، يمكنك تشغيل طلب cURL التالي من خلال رمز التحقق:

curl -X GET "localhost:1337/webhook?hub.verify_token=YOUR-VERIFY-TOKEN&hub.challenge=CHALLENGE_ACCEPTED&hub.mode=subscribe"

إذا كانت عملية التحقق من صحة حدث webhook لديك تعمل على النحو المتوقع، فيجب أن يظهر لك ما يلي:

• تم تسجيل WEBHOOK_VERIFIED في سطر الأوامر حيث يتم تشغيل عملية العقدة.
• تم تسجيل CHALLENGE_ACCEPTED في سطر الأوامر حيث أرسلت طلب cURL.

لاختبار حدث webhook، أرسل طلب cURL التالي:

curl -H "Content-Type: application/json" -X POST "localhost:1337/webhook" -d '{"object": "page", "entry": [{"messaging": [{"message": "TEST_MESSAGE"}]}]}'

إذا كان حدث webhook الذي تستخدمه يعمل على النحو المتوقع، فيجب أن يظهر لك ما يلي:

• تم تسجيل TEST_MESSAGE في سطر الأوامر حيث يتم تشغيل عملية العقدة.
• تم تسجيل EVENT RECEIVED في سطر الأوامر حيث أرسلت طلب cURL.

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

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

في هذا المثال، سنستخدم لوحة المعلومات لتكوين حدث Webhook والاشتراك في الحقل messages. عندما يرسل العميل رسالة إلى تطبيقك في أي وقت، سيتم إرسال إشعار إلى نقطة نهاية webhooks.

1. في لوحة معلومات التطبيق، انتقل إلى المنتجات > Messenger > الإعدادات.
   • لا تتوفر بعض أحداث webhooks لمنصة Messenger للمراسلة في Instagram. إذا كنت تريد تنفيذ أحداث webhooks فقط في Instagram وتعرف أحداث webhooks المتوفرة للمراسلة في Instagram، فيمكنك الاشتراك في أحداث webhooks من هنا. لعرض أحداث webhooks للمراسلة في Instagram والاشتراك فيها، يمكنك الانتقال إلى إعدادات Instagram.

2. أدخل عنوان URL نقطة النهاية في الحقل عنوان URL للاستدعاء وأضف رمز التحقق إلى الحقل رمز التحقق. وسنقوم بتضمين هذه السلسلة في كل طلبات التحقق. إذا كنت تستخدم واحدة من عينات التطبيقات التي نوفرها، فيجب أن تكون هذه هي السلسلة نفسها التي استخدمتها في متغير تكوين TOKEN بتطبيقك.

3. اشترك في الحقول التي تريد إرسال إشعارات لها وانقر على حفظ.

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

   في حالة إعداد نقطة النهاية بشكل صحيح، يجب أن تتحقق من حمولة البيانات وتقوم بتنفيذ الرمز الذي قمت بإعداده بناءً على التحقق الناجح. وإذا كنت تستخدم عينة التطبيق التي نوفرها، فقم بتحميل عنوان URL الخاص بالتطبيق في متصفح الويب لديك. كما يجب أن يعرض محتويات حمولة البيانات.

يمكنك تغيير اشتراكات أحداث Webhooks أو رمز التحقق أو إصدار API في أي وقت باستخدام لوحة معلومات التطبيق.

ملاحظة: يوصى باستخدام أحدث إصدار API لتلقي كل المعلومات المتوفرة حول كل حدث webhook.

يمكنك أيضًا إجراء ذلك بطريقة برمجية عن طريق استخدام نقطة النهاية /app/subscriptions.

حقول منصة Messenger المتوفرة

ربط التطبيق

ستحتاج إلى ربط تطبيق Webhooks بالصفحة وتسجيل اشتراك صفحتك في إشعارات Webhooks التي تريد تلقيها.

إضافة التطبيق

يمكنك ربط التطبيق بصفحة ما في Meta Business Suite > كل الأدوات > تطبيقات الأعمال

ملاحظة: ستحتاج إلى تسجيل اشتراك كل تطبيقات المراسلة لدى نشاطك التجاري في أحداث webhooks المراسلة.

تسجيل اشترك الصفحة

ستحتاج إلى تسجيل اشتراك صفحتك في إشعارات Webhooks التي تريد تلقيها.

المتطلبات

• رمز وصول الصفحة المطلوب من جانب شخص يمكنه تنفيذ المهمة MODERATE على الصفحة التي يتم الاستعلام عنها
• الإذنان pages_messaging وpages_manage_metadata

للاشتراك في حقل أحداث Webhooks، أرسل طلب POST إلى عنصر الربط subscribed_apps في الصفحة باستخدام رمز وصول الصفحة.

curl -i -X POST "https://graph.facebook.com/PAGE-ID/subscribed_apps
  ?subscribed_fields=messages
  &access_token=PAGE-ACCESS-TOKEN"

عينة من الاستجابة

{
  "success": "true"
}

لمعرفة التطبيق الذي قامت صفحتك بتثبيته، أرسل طلب GET بدلاً من ذلك:

عينة من الطلب

curl -i -X GET "https://graph.facebook.com/PAGE-ID/subscribed_apps
  &access_token=PAGE-ACCESS-TOKEN"

عينة من الاستجابة

{
  "data": [
    {
      "category": "Business",
      "link": "https://my-clever-domain-name.com/app",
      "name": "My Sample App",
      "id": "APP-ID"
      "subscribed_fields": [
        "messages"
      ]
    }
  ]
}

إذا لم تقم صفحتك بتثبيت أي تطبيقات، فستُرجع واجهة API مجموعة بيانات فارغة.

مستكشف Graph API

يمكنك أيضًا استخدام مستكشف Graph API لإرسال طلب لتسجيل اشتراك صفحتك في حقل أحداث Webhooks.

1. حدّد تطبيقك في قائمة التطبيق المنسدلة.
2. انقر على قائمة الحصول على الرمز المنسدلة وحدّد الحصول على رمز وصول المستخدم، ثم اختر الإذن pages_manage_metadata. وسيؤدي هذا إلى استبدال رمز التطبيق برمز وصول المستخدم من خلال الإذن pages_manage_metadata الذي تم منحه.
3. انقر على الحصول على رمز مجددًا وحدّد صفحتك. وسيؤدي هذا إلى استبدال رمز وصول المستخدم برمز وصول الصفحة.
4. قم بتغيير طريقة التشغيل من خلال النقر على القائمة المنسدلة GET وتحديد POST.
5. استبدل استعلام me?fields=id,name الافتراضي بمعرف الصفحة المتبوع بـ /subscribed_apps، ثم أرسل الاستعلام.

متطلبات الوصول

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

تعرف على المزيد حول الوصول القياسي والوصول المتقدم ، والبيانات التي يمكن الوصول إليها من خلال كل نوع وصول، ومتطلبات التنفيذ.

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

استكشاف عينة التطبيق - يمكنك تنزيل رمز عينة التطبيق للتعرف على المزيد حول الميزات التي توفرها منصة Messenger.

راجع أيضًا

• تعرف على كيفية الحصول على الإشعارات عند تمرير محادثة من تطبيق إلى آخر باستخدام بروتوكول التسليم في Messenger
• تعرف على المزيد حول أحداث Webhooks من Meta لواجهة Graph API