إعداد أحداث Webhooks في Instagram

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

تلقي إشعارات Webhook المباشرة

لتلقي إشعارات webhook مباشرة، يجب استيفاء الشروط التالية:

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

• يجب أن يمنح مستخدم التطبيق الأذونات المناسبة لتطبيقك (الإذن instagram_manage_insights بالنسبة للقصص، والإذن instagram_manage_comments بالنسبة للتعليقات و@عمليات الذكر).
• يجب تمكين اشتراكات الصفحة في الصفحة المتصلة بحساب مستخدم التطبيق.
• يجب التحقق من النشاط التجاري المتصل بصفحة مستخدم التطبيق.
• لا يجب على مالك كائن الوسائط الذي يظهر على أساسه التعليق أو @الذكر تعيين حسابه إلى خاص.

التقييدات

• لا تتضمن إشعارات أحداث Webhooks للتعليقات على الألبومات معرف الألبوم. ويمكنك الحصول على معرف الألبوم من خلال الاستعلام عن معرف التعليق الموجود في حدث webhook وطلب الحقل media المرتبط به.
• لا تتلقى التطبيقات إشعارات webhook إذا تم إنشاء الوسائط التي يظهر بها التعليق أو @الذكر بواسطة حساب خاص.
• سيتم إرجاع أدوات قياس رؤى القصة التي يقل عددها عن 5 بالقيمة -1.
• لن تتلقى التطبيقات إلا إشعارات webhook للتعليقات على وسائط IG المباشرة إذا كانت الوسائط قيد البث.
• لا يتم دعم ريلز.
• يجب أن يكون تطبيقك قد أكمل عملية مراجعة التطبيقات بنجاح (الوصول المتقدم) لاستلام إشعارات webhooks لحقلي webhooks comments وlive_comments.
• إذا تم استخدام الوسائط للإعلانات الديناميكية، فلن يتم إرجاع معرف الإعلان.

الخطوة الأولى: إنشاء نقطة نهاية

أنشئ نقطة نهاية تقبل أحداث webhooks وتعالجها. وأثناء التكوين، حدّد الكائن واجهة Instagram Graph API وانقر على إعداد واشترك في واحد أو أكثر من حقول Instagram.

حقول Instagram

الخطوة الثانية: تمكين اشتراكات الصفحة

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

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

• رمز وصول الصفحة لمستخدم التطبيق
• pages_manage_metadata

بنية الطلب

POST /{page-id}/subscribed_apps
  ?access_token={access-token}
  &subscribed_fields={fields}

معلمات الطلب

لا يتلقى تطبيقك إشعارات حول التغييرات الطارئة على حقل إلا إذا تمكّنت من تكوين اشتراكات الصفحة في لوحة معلومات التطبيق والاشتراك في هذا الحقل.

عينة من الطلب

curl -i -X POST \
  "https://graph.facebook.com/v21.0/1755847768034402/subscribed_apps?subscribed_fields=feed&access_token=EAAFB..."

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

{
  "success": true
}

الاستخدامات الشائعة

الحصول على رؤى القصة

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

عينة من حمولة بيانات رؤى القصة

[
  {
    "entry": [
      {
        "changes": [
          {
            "field": "story_insights",
            "value": {
              "media_id": "18023345989012587",
              "exits": 1,
              "replies": 0,
              "reach": 17,
              "taps_forward": 12,
              "taps_back": 0,
              "impressions": 28
            }
          }
        ],
        "id": "17841405309211844",  // Instagram Business or Creator Account ID
        "time": 1547687043
      }
    ],
    "object": "instagram"
  }
]

الرد على عمليات @الذكر في التعليق

إذا اشتركت في الحقل mentions، فسنرسل إلى نقطة النهاية لديك إشعار webhook عند @ذكر مستخدم Instagram لحساب Instagram للأعمال أو حساب منشئ المحتوى على Instagram في تعليق أو شرح توضيحي.

فعلى سبيل المثال، إليك عينة من حمولة بيانات إشعار webhook للتعليق تم إرسالها لحساب Instagram للأعمال (17841405726653026):

عينة من حمولة بيانات تعليق يتضمن @ذِكرًا

[
  {
    "entry": [
      {
        "changes": [
          {
            "field": "mentions",
            "value": {
              "comment_id": "17894227972186120",
              "media_id": "17918195224117851"
            }
          }
        ],
        "id": "17841405726653026",
        "time": 1520622968
      }
    ],
    "object": "instagram"
  }
]

الحصول على محتوى التعليق

للحصول على محتوى التعليق، استخدم الخاصية comment_id للاستعلام عن عنصر الربط GET /{ig-user-id}/mentioned_comment:

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

GET https://graph.facebook.com/17841405726653026 ?fields=mentioned_comment.comment_id(17894227972186120) 

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

{
  "mentioned_comment": {
    "timestamp": "2018-03-20T00:05:29+0000",
    "text": "@bluebottle challenge?",
    "id": "17894227972186120"
  },
  "id": "17841405726653026"
}

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

عند الحصول على الاستجابة، يمكنك تحليل حمولة بيانات الخاصية text لتحديد ما إذا كنت تريد الرد على التعليق أم لا. وللرد، استخدم قيم الخاصية caption_id وmedia_id الخاصة بحمولة بيانات إشعار Webhook للاستعلام عن نقطة النهاية POST /{ig-user-id}/mentions:

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

curl -i -X POST \
  -d "comment_id=17894227972186120" \
  -d "media_id=17918195224117851" \
  -d "message=Challenge%20accepted!" \
  -d "access_token={access-token}" \
  "https://graph.facebook.com/17841405726653026/mentions"

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

{
  "id": "17911496353086895"
}

الرد على عمليات @الذكر في الشرح التوضيحي

إذا اشتركت في الحقل mentions، فسنرسل إلى نقطة النهاية لديك إشعار webhook عند @ذكر المستخدم لحساب Instagram للأعمال أو حساب منشئ المحتوى على Instagram في تعليق أو شرح توضيحي على كائن وسائط لا يملكه النشاط التجاري أو منشئ المحتوى.

فعلى سبيل المثال، إليك عينة من إشعار webhook لعملية @ذكر في شرح توضيحي تم إرسالها لحساب Instagram للأعمال (17841405726653026):

إشعار Webhook لعملية @ذكر في شرح توضيحي

[
  {
    "entry": [
      {
        "changes": [
          {
            "field": "mentions",
            "value": {
              "media_id": "17918195224117851"
            }
          }
        ],
        "id": "17841405726653026",
        "time": 1520622968
      }
    ],
    "object": "instagram"
  }
]

الحصول على محتوى الشرح التوضيحي

للحصول على محتوى الشرح التوضيحي، استخدم الخاصية media_id للاستعلام عن عنصر الربط GET /{ig-user-id}/mentioned_media:

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

GET https://graph.facebook.com/17841405726653026 ?fields=mentioned_media.media_id(17918195224117851){caption,media_type} 

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

{
  "mentioned_media": {
    "caption": "@bluebottle There can be only one!",
    "media_type": "IMAGE",
    "id": "17918195224117851"
  },
  "id": "17841405726653026"
}

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

عند الحصول على الاستجابة، يمكنك تحليل حمولة بيانات الخاصية caption لتحديد ما إذا كنت تريد الرد على التعليق أم لا. وللرد، استخدم الخاصية media_id الخاصة بحدث Webhook للاستعلام عن عنصر الربط POST /{ig-user-id}/mentions:

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

curl -i -X POST \
  -d "media_id=17918195224117851" \
  -d "message=MacLeod%20agrees!" \
  -d "access_token={access-token}" \
  "https://graph.facebook.com/17841405726653026/mentions"

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

{
  "id": "17911496353086895"
}