خطاف الويب (webhook) للإشارة على Facebook: متى يشير أحد إلى صفحتك
يُبلغ حقل mention في خطافات صفحات Facebook التطبيقَ حين يشير أحد إلى الصفحة في منشور أو تعليق. ترسل Meta تغييرًا بقيمة mention في الحقل field، وقد تحمل قيمته post_id، وcomment_id في حالة التعليق، والنصَّ في message، والروابطَ والوسائطَ المرفقة، وitem وverb، وذلك في طلب POST موقَّع بالترويسة X-Hub-Signature-256.
يشترك easyCoexistence في حقل mention لكل صفحة تربطها، إلى جانب feed وmessages، ويُرسل أحداث الإشارة إلى نقطة النهاية HTTPS الخاصة بك فور وصولها، موقّعة بسر خاص بتلك الصفحة ودون الاحتفاظ بأي نسخة، ليعلم وكيلك بكل إشارة لحظة حدوثها.
حقل خطاف صفحة Facebook للإشارات الجديدة إلى الصفحة، بما في ذلك الإشارات في التعليقات والمنشورات.
الصلاحية التي يجب أن يمنحها مدير الصفحة بامتيازات MODERATE قبل أن تصل خطافات الصفحة إلى عنوان الاستدعاء (callback URL) الخاص بالتطبيق.
طريقة الإشارة إلى الصفحة في منشور أو تعليق: اكتب @ واسم الصفحة، ثم اخترها.
المدة التي تعيد فيها Meta محاولة إرسال إشعار صفحة فشل، بتكرار متناقص، قبل إسقاطه.
الحقل الذي تضيفه نقطة /{page-id}/tagged إلى كل منشور عام وُسمت فيه الصفحة.
ما الذي يُطلق خطاف الإشارة؟
شخص يشير إلى الصفحة في منشور أو تعليق. على Facebook تتم الإشارة بكتابة @ واسم الصفحة واختيارها من الاقتراحات، ويصف مرجع Meta الحقل بأنه الإشارات الجديدة إلى الصفحة، بما في ذلك الإشارات في التعليقات والمنشورات. ويشير مركز مساعدة Facebook إلى أن إعدادات الصفحة قد تمنع الناس من الإشارة إليها.
كيف يبدو إشعار الإشارة؟
طلب POST بقيمة object تساوي page، وإدخال واحد entry للصفحة المُشار إليها: معرّفها ووقت، ومصفوفة changes يكون حقلها field هو mention. يسرد مرجع Meta حقول القيمة دون نموذج، لذلك شُكّل هذا المثال للإشارة في منشور من تلك القائمة:
{
"object": "page",
"entry": [
{
"id": "<PAGE_ID>",
"time": 1793520000,
"changes": [
{
"field": "mention",
"value": {
"item": "post",
"verb": "add",
"post_id": "<POST_ID>",
"message": "<TEXT_WITH_THE_MENTION>"
}
}
]
}
]
}ما معنى كل حقل من حقول الإشارة؟
هذه حقول القيمة كما يسردها مرجع Meta، وأيها يحمله الإشعار يتوقف على المنشور أو التعليق:
post_id: معرّف المنشور الذي أشار إلى الصفحة.comment_id: معرّف التعليق عندما تكون الإشارة فيه، وparent_id: معرّف تعليقه الأصلي.- message: النص الذي يحمل الإشارة.
- link وphoto وphotos وvideo: روابط لما أرفقه المنشور أو التعليق.
- item وverb: نوع العنصر وما حدث له، من القوائم نفسها التي يستخدمها حقل feed.
created_time: وقت إنشاء المنشور أو التعليق.- from و
message_tags: الكاتب والملفات الشخصية الموسومة في النص، وكلاهما مقتصر على Workplace only. - أيضًا ضمن القائمة: action و
album_idوevent_idوphoto_idوvideo_idوshare_idوpublished وreaction_typeوrecipient_idوopen_graph_story_id.
أي صلاحية يحتاجها حقل الإشارة؟
pages_manage_metadata، التي تشترط Meta أن يمنحها مدير الصفحة بامتيازات MODERATE قبل أن تصل خطافات الصفحة إلى التطبيق. تُشترك الصفحة عبر POST /{page-id}/subscribed_apps مع mention ضمن subscribed_fields، باستخدام رمز الوصول (token) للصفحة من شخص يملك المهمة CREATE_CONTENT أو MANAGE أو MODERATE، مع pages_manage_metadata وpages_show_list. ويشترك التطبيق في mention أيضًا، لأن الحقول لا تُسلَّم إلا إذا كانت مشتركة على المستويين، والصفحات التي يديرها أشخاص لا دور لهم في التطبيق تحتاج هذه الصلاحيات في الوصول المتقدم (Advanced Access).
كيف تقرأ المنشور أو التعليق الذي يشير إلى الصفحة؟
بمعرّفه، باستخدام رمز وصول الصفحة حيثما تسمح Meta بذلك. يقرأ رمز الصفحة المنشورات المنشورة إلى الصفحة أو منها، أما المنشورات العامة التي تشاركها صفحات أخرى فتحتاج pages_manage_posts وميزة Page Public Content Access، على رمز من مدير الصفحة؛ وتربط Meta قراءة منشور شخص بصلاحية user_posts الخاصة بذلك الشخص.
GET https://graph.facebook.com/<POST_ID>
?fields=message,permalink_url,created_time
&access_token=<PAGE_ACCESS_TOKEN>
GET https://graph.facebook.com/<COMMENT_ID>
?fields=message,from,created_time
&access_token=<PAGE_ACCESS_TOKEN>أين تجد الصفحة إشاراتها الأخرى؟
في الحافة (edge) tagged. تسرد GET /{page-id}/tagged المنشورات العامة التي وُسمت فيها الصفحة، ولكل منها tagged_time، وتشمل أيضًا المنشورات السابقة على إعداد الخطاف. تحتاج رمز وصول للصفحة من شخص يملك المهمة CREATE_CONTENT أو MANAGE أو MODERATE، مع pages_read_user_content وpages_show_list، وتقول Meta إن ميزة Page Public Content Access قد تكون مطلوبة. وفي منشور لشخص، تعيد Meta الحقل from لكاتب المنشور وحده.
كيف يسلّم easyCoexistence أحداث الإشارة؟
يشترك كل صفحة في mention إلى جانب feed وmessages عند ربطها. ويتحقق تطبيقه من الترويسة X-Hub-Signature-256 في كل تسليم، ويرد على Meta فورًا، ثم يرسل كل إدخال للصفحة دون تعديل إلى نقطة النهاية HTTPS التي تحددها بـ set_social_webhook_destination أو PUT /channels/:id/webhook في Partner API:
- الترويسة X-EC-Signature تحمل t=<unix>,v1=<hex>: وهي HMAC-SHA256 للطابع الزمني، ثم نقطة، ثم الجسم الخام، ومفتاحه سر توقيع الصفحة.
- يبدأ السر بـ whsec_ ويُعرض مرة واحدة؛ وإعادة ضبط عنوان URL تُصدر سرًا جديدًا، وضبطه على null يوقف التوجيه.
- يُرسل كل إدخال مرة واحدة، مع انتظار حتى 8 ثوانٍ، إلى عنوان HTTPS يُحلّ إلى IP عام، دون متابعة أي إعادة توجيه ودون الاحتفاظ بنسخة.
POST <YOUR_ENDPOINT>
Content-Type: application/json
X-EC-Signature: t=1793520001,v1=<HEX_HMAC_SHA256>
{
"platform": "facebook",
"account_id": "<ACCOUNT_ID>",
"external_id": "<PAGE_ID>",
"entry": {
"id": "<PAGE_ID>",
"time": 1793520000,
"changes": [
{
"field": "mention",
"value": {
"item": "post",
"verb": "add",
"post_id": "<POST_ID>",
"message": "<TEXT_WITH_THE_MENTION>"
}
}
]
}
}الأخطاء الشائعة
- قراءة entry.time على أنه لحظة الإشارة. تضبطه Meta على وقت إرسال الإشعار، أما created_time داخل القيمة فيؤرخ المنشور أو التعليق.
- اعتبار فشل البحث حدثًا معطوبًا. تحذر Meta من أن بعض قيم post_id وcomment_id في إشعارات الإشارة لا يمكن الاستعلام عنها، لنقص الصلاحية أو لأسباب الخصوصية، لذا احتفظ بنص الرسالة من الحدث نفسه.
- جلب المنشور قبل الرد على الإرسال. لا تُعاد محاولات الإرسال، لذا أعِد 2xx فورًا وابحث عن المنشور لاحقًا.
يبدأ السعر من US$ 9 لكل اتصال في الشهر وينخفض إلى US$ 0.75 كلما أضفت اتصالات، مع فترة تجريبية مجانية مدتها 3 أيام.
الأسئلة الشائعة
هل يذكر خطاف الإشارة من أشار إلى الصفحة؟
ليس بالنسبة إلى الصفحة: يعلّم مرجع Meta الحقل from بأنه مقتصر على Workplace. أما البحث عن المنشور أو التعليق بمعرّفه فقد يعيد كاتبه، حيث تسمح صلاحيات Meta بذلك.
هل يمكنني الحصول على إشارات سابقة على اشتراك الصفحة؟
ليس من الخطاف، لأن Meta لا تحتفظ بسجل إشعارات يمكن الاستعلام عنه. وتسرد الحافة tagged المنشورات العامة التي وُسمت فيها الصفحة.
ما الفرق بين حقل الإشارة وحقل feed؟
يُبلغ feed بالتغييرات على خلاصة الصفحة نفسها، كالمنشورات والتعليقات والتفاعلات فيها؛ ويُبلغ mention بإشارة الصفحة في منشور أو تعليق. ويُشترك في كل حقل على حدة.
هل تنطبق قواعد التعليقات في easyCoexistence على الإشارات؟
لا. تعمل القواعد والأتمتة على التعليقات من حقل feed وعلى رسائل Messenger، أما تغييرات الإشارة فتُرسل إلى نقطة النهاية الخاصة بك كما أرسلتها Meta تمامًا.
تابع القراءة
اربط قناتك الأولى في دقيقتين.
لا حاجة لانتظار مراجعات المنصات. اربط WhatsApp أو Instagram أو TikTok أو أي قناة أخرى، ثم اطلب من الذكاء الاصطناعي النشر أو الرد أو إعداد التقارير، وشاهده يعمل.
- 3 أيام مجانًا
- إلغاء في أي وقت
- واجهات API الرسمية فقط
- مراقبة على مدار الساعة 24/7
تم التحقق في