تسجيل الدخولابدأ الفترة التجريبية المجانية
easyCoexistence واجهات API الرسمية

خطاف الويب (webhook) لـ Messenger في صفحات Facebook: الرسائل وأحداث الإشارات

يُطلق حقل messages في خطاف الويب (webhook) الخاص بصفحات Facebook عندما يرسل شخص رسالة Messenger إلى الصفحة، فيسلّم مصفوفة messaging تتضمن معرّف المرسل المرتبط بالصفحة، ومعرّف الصفحة، والطابع الزمني، وmid الرسالة مع نصها أو مرفقاتها. ويبلغ حقل mention عن الإشارات الجديدة إلى الصفحة في المنشورات والتعليقات، ويوقّع Meta كليهما بالترويسة X-Hub-Signature-256.

تمرّر easyCoexistence رسائل Messenger والإشارات لكل صفحة متصلة إلى نقطة النهاية عبر HTTPS فور وصولها، موقّعة بسر خاص بتلك الصفحة ودون حفظ أي نسخة، ويرد send_social_dm داخل نافذة 24 ساعة.

5 seconds

المهلة التي يطلب فيها Meta من نقطة نهاية Messenger webhook أن ترد على كل إشعار بالرمز 200 OK.

1 hour

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

PSID

معرّف المرسل المرتبط بالصفحة Page-scoped ID في حدث messages، وهو فريد لكل شخص وصفحة.

Workplace only

كيف يحدد مرجع Meta حقل المرسل في حدث الإشارة.

No history

لا يمكن الاستعلام لاحقًا عن إشعارات webhook السابقة، لذا على المستلم أن يخزّن ما يحتاجه.

ماذا يرسل حقل messages؟

إشعار عندما يرسل شخص رسالة Messenger إلى الصفحة. يرسل Meta رسائل نصية أو رسائل مع مرفقات، وقد تكون صورًا أو تسجيلات صوتية أو فيديو أو ملفات أو ملصقات، إلى جانب أنواع أخرى، ويمكن أن يصل رابط مشترك كمرفق احتياطي. تحمل الرسالة التي تردّ على رسالة سابقة الحقل reply_to بمعرّف mid تلك الرسالة، وتحمل الرسالة الجاهزة الحقل payload الخاص بها.

كيف يبدو حدث messages؟

على خلاف تغييرات الخلاصة، تصل الرسالة داخل مصفوفة messaging ضمن entry الخاص بالصفحة. لكل حدث: sender، وهو معرّف الشخص المرتبط بالصفحة Page-scoped ID؛ وrecipient، وهو الصفحة؛ وtimestamp؛ وmessage، ويحتوي على mid والنص، أو attachments مع type وpayload URL:

A messages event, as Meta sends it
{
  "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 ساعة:

A forwarded messages event
{
  "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 دقائق.

Node.js: verifying X-EC-Signature
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 الرسالة كمفتاح قبل التصرف.
إنجاز ذلك باستخدام EasyCoexistence

فعّل التمرير بـ 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 ساعة من رسالة الشخص.

تابع القراءة

خطاف الويب (webhook) لـ feed صفحة Facebook: أحداث التعليقات والمنشورات والتفاعلاتما يرسله خطاف feed صفحة Facebook للتعليقات والمنشورات والتفاعلات: حقلا item وverb، وشكل الحمولة في Meta، وكيفية اشتراك الصفحة.نافذة 24 ساعة في Messenger: متى يمكن لصفحة Facebook مراسلة شخص مامتى يمكن لصفحة Facebook مراسلة أحد عبر Messenger: نافذة الرسائل القياسية 24 ساعة، والإجراءات التي تفتحها، وحتى 7 أيام بعد إعلان نقر إلى Messenger.واجهة API للرد الخاص على Facebook: أرسل رسالة لمن علّق على الصفحةأرسل ردًا خاصًا على Facebook عبر API من Meta: POST /{page-id}/messages مع معرّف التعليق، ورسالة واحدة على Messenger خلال 7 أيام، والأخطاء.أذونات واجهة برمجة التطبيقات (API) لصفحات Facebook ومتطلبات مراجعة التطبيقالأذونات التسعة لصفحات Facebook، وما يتيحه كل منها، وما تطلبه مراجعة التطبيق من Meta: Advanced Access، والتحقق من النشاط التجاري، وتسجيل الشاشة.رمز الوصول (token) لصفحة Facebook: مدة صلاحيته وما الذي يُبطلهكيف يُحصل على token لصفحة Facebook بلا تاريخ انتهاء، ومن يستطيع ذلك، وما الذي يجعل Meta يتوقف عن قبوله.خطأ Facebook 551: الشخص غير متاح على Messengerخطأ Facebook 551، الرسالة: This person isn't available right now. تعذّر على Messenger الوصول إلى شخص ربما حظر الصفحة أو أوقف حسابه.

اربط قناتك الأولى في دقيقتين.

لا حاجة لانتظار مراجعات المنصات. اربط WhatsApp أو Instagram أو TikTok أو أي قناة أخرى، ثم اطلب من الذكاء الاصطناعي النشر أو الرد أو إعداد التقارير، وشاهده يعمل.

  • 3 أيام مجانًا
  • إلغاء في أي وقت
  • واجهات API الرسمية فقط
  • مراقبة على مدار الساعة 24/7

تم التحقق في