خطاف الويب (webhook) لـ Messenger في صفحات Facebook: الرسائل وأحداث الإشارات
يُطلق حقل messages في خطاف الويب (webhook) الخاص بصفحات Facebook عندما يرسل شخص رسالة Messenger إلى الصفحة، فيسلّم مصفوفة messaging تتضمن معرّف المرسل المرتبط بالصفحة، ومعرّف الصفحة، والطابع الزمني، وmid الرسالة مع نصها أو مرفقاتها. ويبلغ حقل mention عن الإشارات الجديدة إلى الصفحة في المنشورات والتعليقات، ويوقّع Meta كليهما بالترويسة X-Hub-Signature-256.
تمرّر easyCoexistence رسائل Messenger والإشارات لكل صفحة متصلة إلى نقطة النهاية عبر HTTPS فور وصولها، موقّعة بسر خاص بتلك الصفحة ودون حفظ أي نسخة، ويرد send_social_dm داخل نافذة 24 ساعة.
المهلة التي يطلب فيها Meta من نقطة نهاية Messenger webhook أن ترد على كل إشعار بالرمز 200 OK.
بعد فشل التسليم لهذه المدة، يلغي Meta اشتراك التطبيق في webhooks الصفحة إلى أن يشترك من جديد.
معرّف المرسل المرتبط بالصفحة Page-scoped ID في حدث messages، وهو فريد لكل شخص وصفحة.
كيف يحدد مرجع Meta حقل المرسل في حدث الإشارة.
لا يمكن الاستعلام لاحقًا عن إشعارات webhook السابقة، لذا على المستلم أن يخزّن ما يحتاجه.
ماذا يرسل حقل messages؟
إشعار عندما يرسل شخص رسالة Messenger إلى الصفحة. يرسل Meta رسائل نصية أو رسائل مع مرفقات، وقد تكون صورًا أو تسجيلات صوتية أو فيديو أو ملفات أو ملصقات، إلى جانب أنواع أخرى، ويمكن أن يصل رابط مشترك كمرفق احتياطي. تحمل الرسالة التي تردّ على رسالة سابقة الحقل reply_to بمعرّف mid تلك الرسالة، وتحمل الرسالة الجاهزة الحقل payload الخاص بها.
كيف يبدو حدث messages؟
على خلاف تغييرات الخلاصة، تصل الرسالة داخل مصفوفة messaging ضمن entry الخاص بالصفحة. لكل حدث: sender، وهو معرّف الشخص المرتبط بالصفحة Page-scoped ID؛ وrecipient، وهو الصفحة؛ وtimestamp؛ وmessage، ويحتوي على mid والنص، أو attachments مع type وpayload URL:
{
"object": "page",
"entry": [
{
"id": "<PAGE_ID>",
"time": 1458692752478,
"messaging": [
{
"sender": { "id": "<PSID>" },
"recipient": { "id": "<PAGE_ID>" },
"timestamp": 1458692752478,
"message": {
"mid": "<MESSAGE_ID>",
"text": "hello, world!"
}
}
]
}
]
}ماذا يرسل حقل mention؟
تغيير بالحقل mention عندما تُذكر الصفحة في منشور أو تعليق، ويحمل post_id أو comment_id، والنص، وأي رابط أو صورة أو فيديو، والحقلين item وverb. ويحذّر Meta من أن بعض معرّفات المنشورات والتعليقات تلك لا يمكن الاستعلام عنها، إما لنقص الإذن أو لأسباب الخصوصية، ويشير مرجعه إلى أن حقل sender خاص بـ Workplace فقط، لذلك قد تصل الإشارة دون مؤلفها.
ما حقول Messenger التي لا تُمرَّر؟
تشترك easyCoexistence للصفحات في messages فقط، لا في message_echoes أو messaging_postbacks أو message_reads أو message_deliveries، لذلك لا تُمرَّر الرسائل التي ترسلها الصفحة، ولا ضغطات الأزرار، ولا إيصالات القراءة أو التسليم. ويعيد الرد المرسل عبر send_social_dm معرّف رسالته الخاص بدلًا من ذلك.
كيف تصل الأحداث إلى نقطة النهاية (endpoint) الخاصة بك؟
يرسل Meta webhook الصفحات إلى التطبيق الذي ثبّتته الصفحة، عبر عنوان callback واحد للتطبيق بأكمله. تتحقق easyCoexistence من X-Hub-Signature-256 في كل تسليم، وترد على Meta فورًا، وتمرر كل entry لصفحة متصلة إلى نقطة النهاية عبر HTTPS التي تحددها لتلك الصفحة، موقّعة بالسر الخاص بتلك الصفحة. اضبطها بـ set_social_webhook_destination من Claude أو ChatGPT، أو بـ PUT /channels/:id/webhook عبر Partner API (واجهة برمجة التطبيقات)؛ يُعرض السر مرة واحدة، وإعادة ضبطه تُصدر سرًا جديدًا، والعنوان الفارغ null يوقف التمرير.
كيف يبدو الحدث بعد تمريره؟
طلب POST يحمل الحقل platform، وaccount_id الذي يعيده list_social_accounts لاتصال الصفحة، ومعرّف الصفحة بوصفه external_id، وentry: إدخال Meta الخاص بالصفحة كما هو دون تعديل. الحقل sender.id هو recipient_id الذي يأخذه send_social_dm للرد خلال نافذة 24 ساعة:
{
"platform": "facebook",
"account_id": "<ACCOUNT_ID>",
"external_id": "<PAGE_ID>",
"entry": {
"id": "<PAGE_ID>",
"time": 1793318400000,
"messaging": [
{
"sender": { "id": "<PSID>" },
"recipient": { "id": "<PAGE_ID>" },
"timestamp": 1793318399000,
"message": { "mid": "<MESSAGE_ID>", "text": "<MESSAGE_TEXT>" }
}
]
}
}كيف تتحقق من حدث مُمرَّر؟
يحمل كل طلب POST مُمرَّر ترويسة X-EC-Signature بالصيغة t=<unix>,v1=<hex>، حيث إن v1 هو HMAC-SHA256 للطابع الزمني، ثم نقطة، ثم الجسم الخام، ومفتاحه سر توقيع الصفحة. احسب التوقيع على الجسم كما استُلم تمامًا، وقارن بزمن ثابت، وارفض أي طابع زمني أقدم من 5 دقائق.
import crypto from "node:crypto";
// rawBody: the request body exactly as received, as a string
export function verify(rawBody, header, secret) {
const sig = Object.fromEntries(header.split(",").map((part) => part.split("=")));
if (!sig.t || !sig.v1) return false;
if (Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(sig.t + "." + rawBody)
.digest("hex");
return expected.length === sig.v1.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1));
}هل يُعاد تسليم الحدث عند فشله؟
لا، لا تعيد easyCoexistence المحاولة. يُمرَّر كل entry مرة واحدة فقط، في الذاكرة، دون حفظ نسخة لإعادة المحاولة منها؛ ينتظر التمرير 8 ثوانٍ للحصول على رد، ولا يتبع عمليات إعادة التوجيه، ولا يرسل إلا إلى عنوان HTTPS يُحلّ إلى عنوان IP عام. يشير Meta إلى أن الإشعارات السابقة لا يمكن الاستعلام عنها لاحقًا، لذا احفظ ما تحتاجه فور وصوله. ومن جهة Meta، يعيد محاولة التسليم الفاشل عدة مرات متتالية، فقد تصلك الرسالة نفسها مرتين أحيانًا: أزل التكرار بالاستناد إلى mid الرسالة.
الأخطاء الشائعة
- تنفيذ المعالجة قبل الرد. التمرير لا يعيد المحاولة، لذا أعد 2xx فورًا ثم عالج الحدث بعد ذلك.
- التحقق من التوقيع على JSON محلَّل. احسب HMAC على الجسم الخام كما وصل تمامًا.
- افتراض أن الرسالة تحتوي دائمًا على نص. الملصق أو الصورة أو الرابط المشترك يصل ضمن attachments دون حقل نص.
- تخطي إزالة التكرار. قد يعيد Meta تسليم الحدث بعد فشل، لذا استخدم mid الرسالة كمفتاح قبل التصرف.
فعّل التمرير بـ set_social_webhook_destination أو عبر Partner API. من US$ 9 إلى US$ 0.75 لكل اتصال شهريًا، ينخفض كلما أضفت اتصالات، مع أول 3 أيام مجانًا.
الأسئلة الشائعة
ما حقول webhook التي تشترك فيها easyCoexistence للصفحة؟
messages لرسائل Messenger وmention للإشارات، إلى جانب feed لمنشورات الصفحة وتعليقاتها.
هل يأتي ملصق Messenger أو صورة مع نص؟
لا. يصل الملصق أو الصورة أو الرابط المشترك ضمن attachments، لكل منها type وpayload URL، ولا تحمل الرسالة حقل نص.
ما المدة التي يجب أن ترد فيها نقطة نهاية webhook الخاصة بـ Messenger؟
برمز 200 OK خلال 5 ثوانٍ. وبعد ساعة واحدة من فشل التسليم، يلغي Meta اشتراك التطبيق في webhooks الصفحة.
كيف أرد على رسالة مُمرَّرة؟
استدعِ send_social_dm مع sender.id من الحدث بوصفه recipient_id، خلال 24 ساعة من رسالة الشخص.
تابع القراءة
اربط قناتك الأولى في دقيقتين.
لا حاجة لانتظار مراجعات المنصات. اربط WhatsApp أو Instagram أو TikTok أو أي قناة أخرى، ثم اطلب من الذكاء الاصطناعي النشر أو الرد أو إعداد التقارير، وشاهده يعمل.
- 3 أيام مجانًا
- إلغاء في أي وقت
- واجهات API الرسمية فقط
- مراقبة على مدار الساعة 24/7
تم التحقق في