خطاف الويب (webhook) للرسائل على Instagram: حمولة الرسالة المباشرة (DM) والأصداء والحقول
يسلّم حقل messages في webhook الخاص بحساب Instagram رسائل الحساب المهني المباشرة فور وصولها: النص والمرفقات والمشاركات والردود على القصص والإشارات، والردود المضمّنة والحذف. يحمل كل حدث داخل المصفوفة messaging معرّف المرسل المحدود بنطاق Instagram والمستلم والطابع الزمني وكائن message، والرسائل التي يرسلها الحساب نفسه تعود عبر الحقل ذاته مع ضبط is_echo على true.
يشترك easyCoexistence في messages لكل حساب Instagram متصل، ويعيد توجيه رسائله المباشرة، بما فيها الأصداء، إلى نقطة نهايتك عبر HTTPS فور وصولها، موقّعةً بسرّ ذلك الحساب؛ ولا تحتفظ عملية إعادة التوجيه بنسخة، والرسائل المباشرة غير مخزّنة افتراضيًا.
يُضبط على true في حدث رسالة لرسالة أرسلها الحساب نفسه.
نافذة المراسلة القياسية لمعظم أفعال المستخدمين، التي يمكن خلالها للتطبيق أن يرد على الشخص.
نوع المرفق لمنشور مشارَك؛ كان نوع المشاركة القديم مدعوماً حتى 1 فبراير 2026 فقط.
نوع المرفق لحدث الرسالة المباشرة الذي ترسله Meta عندما يشير شخص إلى الحساب في قصته.
الرمز الفرعي للخطأ، تحت الرمز 200، عندما يعطّل مالك الحساب الوصول إلى الرسائل المباشرة في Instagram.
متى يُطلق حقل messages؟
عندما يرسل شخص رسالة مباشرة إلى الحساب المهني، وعندما يرسل الحساب واحدة. تسرد أمثلة Meta ومراجعها هذه الحالات، وكل منها حدث messaging يحمل كائن message:
- نص، والوسائط كمرفقات: صور وفيديو وصوت وملفات.
- منشور أو Reel مشارَك، كمرفق من النوع
ig_postأوig_reelأو reel. - رد على قصة الحساب، مع
reply_to.story، وقصة تشير إلى الحساب، كمرفق من النوعstory_mention. - رد مضمّن على رسالة سابقة، مع
reply_to.mid، وردّ سريع، معquick_reply.payload. - رسالة حذفها الشخص (
is_deleted)، ووسائط غير مدعومة (is_unsupported)، ورسالة من شخص نقر على إعلان Click-to-Direct (referral). - رسالة أرسلها الحساب، تعود مع ضبط
is_echoعلى true.
كيف يبدو إشعار الرسائل؟
طلب POST يحمل JSON فيه object بقيمة instagram. على عكس التعليق، تقع الرسالة داخل مصفوفة messaging في عنصر entry الخاص بالحساب، وكل عنصر فيها يحمل sender وrecipient وtimestamp وmessage. هكذا يبدو الرد على قصة الحساب:
{
"object": "instagram",
"entry": [
{
"id": "<IG_ID>",
"time": 1793448000512,
"messaging": [
{
"sender": { "id": "<IGSID>" },
"recipient": { "id": "<IG_ID>" },
"timestamp": 1793447999874,
"message": {
"mid": "<MESSAGE_ID>",
"text": "<MESSAGE_TEXT>",
"reply_to": {
"story": {
"url": "<CDN_URL_FOR_THE_STORY>",
"id": "<STORY_ID>"
}
}
}
}
]
}
]
}ماذا يعني كل حقل؟
الحقول التي توثّقها Meta لحدث رسالة ضمن Instagram Login، من الخارج إلى الداخل:
- entry[].id: معرّف الحساب المهني. entry[].time: وقت إرسال Meta للإشعار، وتعطيه عينات الرسائل لدى Meta بالمللي ثانية.
- sender.id وrecipient.id: في رسالة واردة، معرّف الشخص المحدود بنطاق Instagram ومعرّف الحساب؛ وفي الصدى، الزوجان نفسهما معكوسان.
- timestamp: وقت إرسال الرسالة، بالمللي ثانية في عينات Meta. رتّب الرسائل به، لا بترتيب وصولها.
- message.mid: معرّف الرسالة، للإزالة من التكرار والتفاعل والرد على تلك الرسالة عبر
reply_to.mid. - message.text: يظهر عندما تحتوي الرسالة على نص.
- message.attachments[]: كل عنصر فيه type وpayload، غالباً url. ويضيف payload المنشور المشارَك
ig_postإلىig_post_media_idوtitle، وهو التسمية التوضيحية. - message.
reply_to: mid لرد مضمّن، أو story مع url القصة وid لرد على قصة. - message.
quick_reply.payload وmessage.referral: الرد السريع المختار، وref وad_idوsource وtype وads_context_dataالخاصة بإعلان Click-to-Direct. - message.
is_deletedوis_echoوis_selfوis_unsupported: تظهر فقط عندما تكون true. - message.
admin_textوhandoff_reason: في التطبيقات المؤهلة، إشعار بأن تطبيقاً لدى Meta، مثل Meta Business Agent، سلّم المحادثة؛ وقد يصل بلا mid أو نص.
كيف تعمل الأصداء؟
عندما يرسل الحساب رسالة، ترسل Meta حدث رسائل لها أيضاً، مع ضبط is_echo على true. فيكون sender.id هو الحساب وrecipient.id معرّف الشخص المحدود بنطاق Instagram، وتحمل رسالة الاختبار التي يرسلها الحساب إلى نفسه is_self أيضاً. تسجّل الأصداء ما قاله الحساب، وهو ما يحتاجه سجل المحادثات، لكن المعالج الذي يقرر ما إذا كان سيرد عليها عليه أن يتجاوزها. لا ترسل Meta صدى عندما يتفاعل الحساب مع رسالة أو يزيل تفاعله.
{
"object": "instagram",
"entry": [
{
"id": "<IG_ID>",
"time": 1793448061203,
"messaging": [
{
"sender": { "id": "<IG_ID>" },
"recipient": { "id": "<IGSID>" },
"timestamp": 1793448060950,
"message": {
"mid": "<MESSAGE_ID>",
"text": "<REPLY_TEXT>",
"is_echo": true
}
}
]
}
]
}بأي معرّف أرد؟
بـ sender.id، معرّف الشخص المحدود بنطاق Instagram. تنشئه Meta حين يرسل شخص رسالة إلى الحساب أو يعلّق على وسائطه، وهو خاص بذلك الشخص وبذلك الحساب. يُرسل الرد عبر POST إلى /<IG_ID>/messages مع ضبط recipient.id عليه. لا يحمل الحدث اسماً ولا اسم مستخدم؛ يعيدهما طلب GET /<IGSID> مع حقول مثل name وusername، لأن الشخص الذي راسل الحساب منح الموافقة التي يتطلبها هذا الاستعلام.
كيف تفتح الرسالة نافذة 24 ساعة؟
لا يمكن للتطبيق مراسلة شخص إلا بعد أن يراسل الحساب، وفقط ضمن نافذة المراسلة القياسية التي يفتحها فعله. لمعظم الأفعال تدوم 24 ساعة، وتصل إلى 7 أيام من أول رسالة تُرسل بعد النقر على إعلان Click-to-Direct. تفتح رسالة جديدة من الشخص نافذة جديدة، لذا فآخر طابع زمني له هو ما يجب تتبعه؛ والصدى رسالة الحساب نفسه ولا يمدّد شيئاً. يمكن للردود التي يكتبها شخص أن تستخدم نافذة Human Agent المنفصلة لدى Meta، ومدتها 7 أيام، ويُوسم الرد بـ human_agent.
ما الذي لا يحمله حدث الرسائل؟
بعض ما قد يبحث عنه المعالج غير موجود، بحسب المراجع الخاصة بالمراسلة لدى Meta:
- اسم الشخص أو اسم مستخدمه: المعرّف المحدود بنطاق Instagram وحده، الذي يحلّه GET /<IGSID>.
- الوسائط التي تُشاهد مرة واحدة: تصل كمرفق مؤقت بلا رابط.
- الصورة الدقيقة في منشور من عدة صور (carousel): التفاعل مع صورة في المنشور أو إعادة توجيهها يُبلّغ عن الصورة الأولى.
- التفاعلات والتعديلات وإيصالات القراءة، وهي تأتي عبر حقول خاصة بها.
- علامة القراءة: الرسالة المُسلَّمة عبر webhook تبقى غير مقروءة في صندوق Instagram حتى يُرسل رد.
ما حقول الرسائل الأخرى التي تذكرها Meta؟
تذكر قائمة Meta للحقول وأمثلتها لـ Instagram Login هذه الأحداث إلى جانب messages، وكل منها حدث رسائل مستقل. يشترك easyCoexistence في messages والتعليقات والإشارات فقط لكل حساب، لذلك لا يعيد توجيه أيٍّ منها:
message_reactions: يتفاعل شخص مع رسالة أو يزيل تفاعله، مع reaction.mid وaction بقيمة react أو unreact، والتفاعل والرمز التعبيري emoji.message_edit: يعدّل شخص رسالة، معmessage_edit.mid والنص الجديد وnum_edit.messaging_postbacks: ينقر شخص على زر من نوع icebreaker أو على زر قالب، مع postback.mid وtitle وpayload.messaging_referral: شخص في محادثة بالفعل يفتح رابط ig.me مع المعامل ref.messaging_seen: يقرأ شخص رسالة، مع read.mid.messaging_optinsوmessaging_handoverوstandby: آخر اثنين للتطبيقات التي تشارك محادثة بموجب بروتوكول التسليم لدى Meta.
ما الذي يجب أن يفعّله الحساب؟
«السماح بالوصول إلى الرسائل». تشترط Meta تفعيل هذا الخيار في الحساب المهني قبل إدارة رسائله عبر واجهة برمجة التطبيقات (API)، من تطبيق Instagram: الإعدادات، ثم الرسائل والردود على القصص، ثم عناصر التحكم في الرسائل، ثم الأدوات المتصلة. وطالما كان الخيار مُعطَّلاً تفشل الإرسالات برمز 200 والرمز الفرعي 2534041. ويحتاج التطبيق أيضاً إلى instagram_business_basic وinstagram_business_manage_messages، مع Advanced Access لخدمة حسابات لا يملكها أو يديرها.
كيف يعيد easyCoexistence توجيه الرسالة المباشرة؟
مثل التعليق: يُرسل كل عنصر تسلّمه Meta للحساب بطلب POST إلى نقطة نهايتك (endpoint) عبر HTTPS، داخل مغلّف يضم platform وaccount_id وexternal_id وentry، موقّعاً في X-EC-Signature بسرّ الحساب، مرة واحدة دون الاحتفاظ بنسخة. تُعاد توجيه الأصداء مع الباقي، لذا تحقق من is_echo قبل الرد. للرد، استدعِ send_social_dm مع account_id، وsender.id للحدث بوصفه recipient_id، ضمن نافذة 24 ساعة. تعمل الأتمتة التي تبدأ برسالة مباشرة على الأحداث نفسها.
{
"platform": "instagram",
"account_id": "<ACCOUNT_ID>",
"external_id": "<IG_ID>",
"entry": {
"id": "<IG_ID>",
"time": 1793448000512,
"messaging": [
{
"sender": { "id": "<IGSID>" },
"recipient": { "id": "<IG_ID>" },
"timestamp": 1793447999874,
"message": {
"mid": "<MESSAGE_ID>",
"attachments": [
{ "type": "image", "payload": { "url": "<URL_FOR_THE_MEDIA>" } }
]
}
}
]
}
}الأخطاء الشائعة
- الرد على الأصداء. الحدث الذي يضبط is_echo هو رسالة الحساب نفسه، والرد عليه يدخل الحساب في حلقة مع نفسه.
- افتراض أن الرسالة تحمل نصاً دائماً. المرفقات والمشاركات وإشارات القصص والحذف تصل بلا حقل نص، لذا افحص ما يحتويه كائن message.
- ترتيب الرسائل حسب وقت الوصول. قد ترسل Meta الرسائل خارج ترتيبها بعد عطل، لذا رتّبها حسب timestamp.
- قراءة time وtimestamp كثوانٍ. تعطيهما عينات الرسائل لدى Meta بالمللي ثانية، وقراءتهما كثوانٍ تحوّلهما إلى تواريخ بعيدة في المستقبل.
يرد send_social_dm ضمن نافذة 24 ساعة، ويمكن للأتمتة أن ترد وحدها بنص ثابت أو بالذكاء الاصطناعي. من US$ 9 إلى US$ 0.75 لكل اتصال شهرياً، ويتناقص كلما أضفت اتصالات، مع فترة تجريبية مجانية مدتها 3 أيام.
الأسئلة الشائعة
هل طوابع الوقت في webhook رسائل Instagram بالثواني أم بالمللي ثانية؟
بالمللي ثانية في عينات الرسائل لدى Meta، لكل من timestamp ووقت الإدخال entry[].time. وإذا قُرئت كثوانٍ تحوّلت إلى تواريخ بعيدة في المستقبل.
كيف أحصل على اسم مستخدم المرسل من webhook رسالة مباشرة في Instagram؟
استدعِ GET /<IGSID> مع حقول مثل name وusername. لا يحمل الحدث إلا المعرّف المحدود بنطاق Instagram للشخص.
لماذا لا تصل webhook الرسائل المباشرة في Instagram؟
تحقّق من أن الحساب فعّل «السماح بالوصول إلى الرسائل»، وأنه مشترك في messages عبر /subscribed_apps، وأن التطبيق في وضع Live مع Advanced Access للحسابات التي لا يملكها.
هل يعيد easyCoexistence توجيه تفاعلات الرسائل في Instagram؟
لا. تأتي التفاعلات عبر message_reactions، وeasyCoexistence يشترك في الحسابات في messages والتعليقات والإشارات فقط.
تابع القراءة
اربط قناتك الأولى في دقيقتين.
لا حاجة لانتظار مراجعات المنصات. اربط WhatsApp أو Instagram أو TikTok أو أي قناة أخرى، ثم اطلب من الذكاء الاصطناعي النشر أو الرد أو إعداد التقارير، وشاهده يعمل.
- 3 أيام مجانًا
- إلغاء في أي وقت
- واجهات API الرسمية فقط
- مراقبة على مدار الساعة 24/7
تم التحقق في