الاشتراك في خطاف الويب (webhook) لصفحة فيسبوك: الحافة subscribed_apps
يُشترك تطبيق في webhooks صفحة فيسبوك عبر POST /{page-id}/subscribed_apps، ويُمرَّر فيه subscribed_fields مثل feed,messages، ورمز الوصول (token) للصفحة من شخص يملك المهمة CREATE_CONTENT أو MANAGE أو MODERATE، مع منح pages_manage_metadata وpages_show_list. ترسل Meta أحداث أي حقل فقط إذا اشترك فيه التطبيق أيضًا، ويُعرض الاشتراك بطلب GET، وتُزال بطلب DELETE على الحافة نفسها.
يشترك easyCoexistence في feed وmessages وmention لكل صفحة تربطها عبر subscribed_apps، ويلغي اشتراكها عند حذفها، ويرسل أحداث الصفحة إلى نقطة نهاية HTTPS الخاصة بك موقّعة بسر خاص بتلك الصفحة، من موصل MCP واحد أو من Partner API.
لا تصل webhooks إلا للحقول المشتركة على مستوى الصفحة ومستوى التطبيق معًا، وقد تُدرج الصفحة حقولًا أكثر مما يُدرجه التطبيق.
مهام الصفحة، ويحتاجها الشخص صاحب الرمز ليقرأ الاشتراك أو ينشئه.
تُعاد مع النجاح عندما يزيل التطبيق اشتراكه من الصفحة بالطلب DELETE على الحافة نفسها.
ما يتطلبه /{app-id}/subscriptions لقراءة الاشتراك على مستوى التطبيق أو إنشائه أو حذفه.
من عمليات تسليم Messenger الفاشلة قبل أن تلغي Meta اشتراك التطبيق من الصفحة حتى يشترك من جديد.
ماذا تفعل حافة subscribed_apps؟
تُثبّت التطبيق على الصفحة وتحدد الحقول التي يتلقاها من حقول webhook الخاصة بها. ترسل Meta الإشعارات فقط ما دام التطبيق مثبتًا على الصفحة ولم تُعطَّل منصة التطبيق في إعداداتها، وفقط للحقول المشتركة على المستويين: مستوى الصفحة عبر هذه الحافة، ومستوى التطبيق المحدد في App Dashboard أو عبر /{app-id}/subscriptions. وقد تُشترك الصفحة في حقول أكثر من التطبيق.
كيف تشترك صفحة؟
بطلب POST إلى الحافة، مع subscribed_fields تُدرج فيه الحقول مفصولة بفواصل، ورمز وصول الصفحة. ينجح الطلب فيعيد success true، وإذا تضمّن الطلب messages فيلزم أيضًا pages_messaging على الرمز:
POST https://graph.facebook.com/{page-id}/subscribed_apps
?subscribed_fields=feed,messages,mention
&access_token=<PAGE_ACCESS_TOKEN>
{ "success": true }أي رمز ومهام وصلاحيات يحتاج؟
رمز وصول للصفحة، يرتبط الطلب بصفحة واحدة، من شخص يستطيع التصرف فيها. تحدد مراجع Meta وأدلتها هذه المتطلبات:
- أي حقل: شخص يملك المهمة
CREATE_CONTENTأو MANAGE أو MODERATE، معpages_manage_metadataوpages_show_listمعًا. - messages وبقية حقول Messenger: تُضاف
pages_messaging، على رمز من شخص يملك مهمة MESSAGING ويستطيع تنفيذها. - leadgen: مهمة ADVERTISE، مع الصلاحيات
leads_retrievalوpages_read_engagementوads_managementمعًا. - قراءة الاشتراك عبر GET تتطلب المهام والصلاحيات نفسها التي يتطلبها إنشاؤه.
أي مستوى وصول تحتاج الحقول؟
Advanced Access، للصفحات والأشخاص من خارج أدوار التطبيق نفسه. مع Standard Access تصل إشعارات Messenger فقط من أشخاص لهم دور في التطبيق، مثل مديريه ومطوريه ومختبريه. أما Advanced Access، الذي يُمنح لكل صلاحية عبر App Review ويتطلب Business Verification، فيفتح الإشعارات لعملاء التطبيق. ويذكر دليل Messenger من Meta نشر التطبيق ضمن المتطلبات المسبقة أيضًا.
ما اشتراك مستوى التطبيق؟
النصف الآخر: الحقول التي يستمع إليها التطبيق نفسه، مع عنوان callback الخاص به. يُضبط في App Dashboard أو بطلب POST إلى /{app-id}/subscriptions برمز وصول التطبيق، ويُمرَّر فيه object=page وcallback_url وfields وinclude_values وverify_token، وهو ما يطلق طلب التحقق من Meta. ويعرض GET على الحافة نفسها callback_url والحقول ومدى نشاط الاشتراك لكل كائن، ويعدّل POST جديد الحقول دون الكتابة فوق الباقي، ويزيل الاشتراكات كلها أو الحقول المذكورة بطلب DELETE.
كيف تتحقق مما تشترك فيه الصفحة؟
بطلب GET إلى الحافة نفسها برمز الصفحة. تسرد المصفوفة data كل تطبيق ثبّتته الصفحة، مع اسمه ومعرّفه وsubscribed_fields، وتعود فارغة إذا لم يكن على الصفحة أي تطبيق مثبت:
GET https://graph.facebook.com/{page-id}/subscribed_apps
?access_token=<PAGE_ACCESS_TOKEN>
{
"data": [
{
"category": "Business",
"link": "https://example.com/app",
"name": "<APP_NAME>",
"id": "<APP_ID>",
"subscribed_fields": ["feed", "messages", "mention"]
}
]
}كيف تزيل اشتراكًا؟
بطلب DELETE إلى /{page-id}/subscribed_apps، الذي يفصل التطبيق عن الصفحة. يستطيع التطبيق إزالة اشتراكه بنفسه برمز وصول التطبيق، وتتضمن الاستجابة success وmessaging_success. وتزيله Meta أيضًا من تلقاء نفسها: بعد ساعة من عمليات تسليم Messenger الفاشلة يُلغى اشتراك التطبيق من الصفحة، ويجب أن يشترك من جديد بعد أن تعمل نقطة النهاية (endpoint) الخاصة به.
ماذا يفعل easyCoexistence عند الربط؟
يشترك في كل صفحة يختارها الشخص مباشرة بعد حفظ رمز تلك الصفحة: POST /{page-id}/subscribed_apps مع subscribed_fields مضبوطة على feed,messages,mention. إذا رفضت Meta، تبقى الصفحة متصلة ويعرض list_social_accounts السبب في last_error. وعند حذف الصفحة يُرسل DELETE /{page-id}/subscribed_apps قبل التخلص من الرمز، ولا تصل أي أداة إلى المسارين subscribed_apps والرموز، فتتولى easyCoexistence إدارة الاشتراك وحدها.
الأخطاء الشائعة
- استدعاء الحافة برمز وصول مستخدم. تحتاج رمز وصول الصفحة المراد الاشتراك فيها.
- اشتراك الصفحة دون التطبيق. لا يصل أي حقل إلى callback إلا إذا تضمّنه اشتراك التطبيق نفسه أيضًا.
- نسيان pages_messaging عند الاشتراك في messages. تشترطه Meta، ويلزم أن يأتي الرمز من شخص يملك مهمة MESSAGING ويستطيع تنفيذها.
- نسيان إعادة الاشتراك بعد انقطاع. ساعة من عمليات Messenger الفاشلة تلغي اشتراك التطبيق، وتتوقف الأحداث حتى يُرسل POST من جديد.
ابتداءً من US$ 9 لكل اتصال شهريًا، ينخفض إلى US$ 0.75 كلما أضفت اتصالات، مع فترة تجريبية مجانية مدتها 3 أيام.
الأسئلة الشائعة
هل أحتاج إلى الاشتراك في كل صفحة على حدة؟
نعم. تعمل subscribed_apps لكل صفحة برمزها الخاص، بينما ينطبق اشتراك مستوى التطبيق على كائن page على الصفحات التي ثبّتت التطبيق.
لماذا تعيد subscribed_apps الخطأ 200؟
تصنّف Meta الخطأ 200 على أنه خطأ صلاحيات لهذه الحافة. تحقق من أن الرمز يحمل pages_manage_metadata وpages_show_list، ومن أنه يأتي من شخص يملك مهمة CREATE_CONTENT أو MANAGE أو MODERATE، أيًّا منها.
هل يمكن اشتراك صفحة من Graph API Explorer؟
نعم. يختار دليل Meta التطبيق، ويحصل على رمز مستخدم بصلاحية pages_manage_metadata، ويبادله برمز الصفحة، ثم يُرسل طلب POST لتلك الحافة على الصفحة.
هل يمكن إضافة حقول webhook إلى صفحة متصلة بـ easyCoexistence؟
ليس عبر أدواته: لا تصل أي منها إلى مسارات subscribed_apps، وتبقى الصفحة مشتركة في الحقول الثلاثة التي يمرّرها التطبيق نفسه.
تابع القراءة
اربط قناتك الأولى في دقيقتين.
لا حاجة لانتظار مراجعات المنصات. اربط WhatsApp أو Instagram أو TikTok أو أي قناة أخرى، ثم اطلب من الذكاء الاصطناعي النشر أو الرد أو إعداد التقارير، وشاهده يعمل.
- 3 أيام مجانًا
- إلغاء في أي وقت
- واجهات API الرسمية فقط
- مراقبة على مدار الساعة 24/7
تم التحقق في