أحداث Instagram عبر خطاف الويب (webhook): التعليقات والإشارات والرسائل المباشرة
تُبلغ أحداث webhook الخاصة بـ Instagram عن النشاط على الحساب الاحترافي لحظة وقوعه: التعليقات الجديدة والإشارات (@mentions) والرسائل المباشرة. تُرسل Meta كل حدث بصيغة JSON عبر POST إلى endpoint من نوع HTTPS الخاص بالتطبيق المتصل، وتُعيد محاولة التسليم الفاشل إليه لمدة تصل إلى 36 ساعة. يمرّر easyCoexistence كل حدث إلى endpoint الخاص بك مرة واحدة، موقّعًا لكل حساب، دون إعادة محاولة. ومع Instagram Login تصل الإشارات ضمن إشعار التعليقات.
المدة التي تُعيد فيها Meta محاولة التسليم الفاشل إلى endpoint التطبيق قبل إسقاطه.
تجمع Meta معظم التحديثات في تسليم webhook واحد، دون أن تضمن ذلك.
العلامة التي تضعها Meta على أحداث الرسائل التي أرسلها الحساب نفسه.
تُفعّل إشعارات التعليقات والإشارات للوسائط على الحسابات العامة فقط.
ما الأحداث المتاحة؟
بالنسبة إلى حساب احترافي متصل عبر Instagram Login، تصل ثلاثة أنواع من النشاط كأحداث:
- التعليقات: تعليق جديد على وسائط الحساب، مع معرّف التعليق، ومعرّف المستخدم الخاص بـ Instagram واسم المستخدم، والنص، ومعرّف الوسائط ونوعها.
- الإشارات: مع Instagram Login تأتي ضمن إشعار التعليقات، لا كحقل مستقل.
- الرسائل: رسالة مباشرة إلى الحساب، مع المُرسِل والمستلم والطابع الزمني والرسالة نفسها، بما فيها النص والمرفقات وردود القصص.
كيف تصل الأحداث إلى endpoint الخاص بك؟
تُسلّم Meta webhooks الخاصة بـ Instagram إلى التطبيق الذي ربطه الحساب. تستقبلها easyCoexistence وتمرّر كل حدث فور وصوله إلى endpoint عبر HTTPS الذي حددته لذلك الحساب، موقّعًا بسر خاص بالحساب.
اضبط endpoint باستخدام set_social_webhook_destination من Claude أو ChatGPT، أو عبر Partner API باستخدام PUT /channels/:id/webhook. يُعرض السر الموقّع مرة واحدة فقط، وإعادة ضبط endpoint تُصدر سرًا جديدًا، وتمرير null بدل الرابط يُوقف التمرير.
كيف يبدو التسليم؟
طلب POST بجسم JSON يتضمن المنصة، وaccount_id الذي تعيده list_social_accounts للاتصال، وexternal_id لحساب Instagram، وentry، وهو إدخال webhook من Meta للحدث دون تغيير. تصل الرسالة المباشرة بالطريقة نفسها، مع مصفوفة messaging بدل changes. وهذا شكل تعليق جديد:
{
"platform": "instagram",
"account_id": "<ACCOUNT_ID>",
"external_id": "<INSTAGRAM_ACCOUNT_ID>",
"entry": {
"id": "<INSTAGRAM_ACCOUNT_ID>",
"time": 1793318400,
"changes": [
{
"field": "comments",
"value": {
"id": "<COMMENT_ID>",
"from": { "id": "<INSTAGRAM_SCOPED_ID>", "username": "<USERNAME>" },
"text": "<COMMENT_TEXT>",
"media": { "id": "<MEDIA_ID>", "media_product_type": "<MEDIA_PRODUCT_TYPE>" }
}
}
]
}
}كيف تتحقق من التسليم؟
يحمل كل تسليم ترويسة 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 المحاولة: التمرير يُرسل كل حدث مرة واحدة، في الذاكرة، ولا يحتفظ بنسخة يُعاد منها. أجب بـ 2xx بسرعة ونفّذ العمل لاحقًا، واحفظ ما تحتاجه عند الوصول، لأن Meta لا تحتفظ بسجل للإشعارات السابقة يمكن الاستعلام عنه أيضًا.
تُعيد Meta نفسها محاولة التسليم الفاشل إلى التطبيق لمدة تصل إلى 36 ساعة، لذا قد يصلك الحدث نفسه مرتين أحيانًا: أزل التكرار بالاعتماد على معرّف التعليق أو mid الخاص بالرسالة.
ماذا يجب أن يتحقق منه المعالج؟
بعض التفاصيل في حمولات Meta تُربك المعالج الأول:
is_echo: حدث الرسالة الذي تكون فيه القيمة true أرسله الحساب نفسه، فلا يحتاج إلى رد.- ردود القصص: الرسالة المباشرة التي ترد على قصة تحمل
reply_toمع معرّف القصة ورابطها. - إشارات القصص: تصل كرسالة يكون نوع مرفقها
story_mention. - time: وقت إرسال Meta للإشعار، لا وقت إنشاء التعليق أو الرسالة؛ أما الطابع الزمني للرسالة فيوجد في إدخال messaging الخاص بها.
- معرّفات الألبومات: لا تتضمنها أحداث التعليقات؛ ابحث عن الألبوم بمعرّف التعليق.
الأخطاء الشائعة
- تنفيذ العمل قبل الرد. التمرير لا يُعيد المحاولة، فأجب بـ 2xx فورًا وعالج الحدث لاحقًا.
- التحقق من التوقيع على JSON محلَّل. احسب HMAC على الجسم الخام كما وصل تمامًا.
- الرد على رسائل is_echo. الرسالة التي تكون فيها القيمة مضبوطة على true هي ما أرسله الحساب نفسه، والرد عليها يبدأ حلقة لا تنتهي.
- تجاهل إزالة التكرار. قد ترسل Meta الحدث نفسه مرة أخرى بعد فشل، فاعتمد على معرّف التعليق أو mid الرسالة.
تمرر easyCoexistence تعليقات حساب Instagram ورسائله المباشرة وإشاراته إلى endpoint الخاص بك عبر HTTPS فور وصولها، موقّعة بسر خاص بالحساب دون الاحتفاظ بنسخة في الطريق. فعّله باستخدام set_social_webhook_destination من Claude أو ChatGPT، أو عبر Partner API. من US$ 9 إلى US$ 0.75 لكل اتصال شهريًا، ينخفض كلما أضفت اتصالات، مع فترة تجريبية مجانية مدتها 3 أيام.
الأسئلة الشائعة
ماذا يعني حقل time في webhook من Instagram؟
وقت إرسال Meta للإشعار، لا وقت إنشاء التعليق أو الرسالة. أما الطابع الزمني للرسالة المباشرة فيوجد في إدخال messaging الخاص بها.
هل تُعيد Meta محاولة تسليم webhook الفاشل من Instagram؟
نعم. تُعيد Meta محاولة التسليم الفاشل إلى التطبيق لمدة تصل إلى 36 ساعة، لذا قد يصل الحدث نفسه مرتين أحيانًا: أزل التكرار بالاعتماد على معرّف التعليق أو mid الرسالة. تُمرر easyCoexistence كل حدث إلى endpoint الخاص بك مرة واحدة، فأجب بـ 2xx بسرعة.
كم تحديثًا يمكن أن يحمل تسليم webhook واحد من Instagram؟
حتى 1,000 عند تجميعها من Meta، مع أن Meta لا تضمن التجميع. كرّر على مصفوفة entry كاملة، لا على عنصرها الأول فقط.
هل للإشارات حدث خاص بها؟
ليس مع Instagram Login. تُدرج Meta الإشارات ضمن إشعار التعليقات، فتصل على المسار نفسه الذي تصل عليه التعليقات.
تابع القراءة
اربط قناتك الأولى في دقيقتين.
لا حاجة لانتظار مراجعات المنصات. اربط WhatsApp أو Instagram أو TikTok أو أي قناة أخرى، ثم اطلب من الذكاء الاصطناعي النشر أو الرد أو إعداد التقارير، وشاهده يعمل.
- 3 أيام مجانًا
- إلغاء في أي وقت
- واجهات API الرسمية فقط
- مراقبة على مدار الساعة 24/7
تم التحقق في