Instagram Messaging API مقابل Graph API — مخطط فِن يُظهر Messaging API كمجموعة فرعية ضمن Graph API، وخريطة نقاط النهاية مع الصلاحيات، ومصفوفة قرار حسب حالة الاستخدام
في هذا الدليل: الإجابة في جملة واحدة · ما الذي يغطّيه Instagram Graph API · ما الذي يعنيه تحديداً "Instagram Messaging API" · خريطة شاملة لفئات نقاط النهاية · الصلاحيات لكل منها · اشتراكات webhook · واجهة API القديمة المُهملة · مصفوفة القرار حسب حالة الاستخدام

الإجابة في جملة واحدة

✓ إجابة مباشرة
"Instagram Messaging API" ليس API منفصلاً — إنه مجموعة فرعية محدّدة من نقاط النهاية والصلاحيات واشتراكات webhook ضمن Instagram Graph API، تركّز حصراً على الرسائل المباشرة. كلاهما يستخدم نفس عنوان URL الأساسي (graph.facebook.com/v21.0)، ونفس نظام المصادقة، ونفس إعداد التطبيق. "Instagram Messaging API" هو الاسم التسويقي الذي تستخدمه Meta للقدرات المخصّصة لرسائل DM ضمن Graph API الأوسع.

ينشأ الالتباس لأن Meta تُسوّق قدرات API مختلفة تحت أسماء منتجات مختلفة — "Instagram Graph API" للمنصة الكاملة، و"Instagram Messaging API" أو "Messenger API for Instagram" للمجموعة الفرعية الخاصة برسائل DM. كثيراً ما يجد المطوّرون الذين يبحثون عن "Instagram Messaging API" توثيقاً يبدو وكأنه نظام مختلف تماماً. ليس كذلك. تُعدّ تطبيق Facebook واحداً، وتحصل على مجموعة واحدة من الرموز، وتستخدم نقاط نهاية وصلاحيات مختلفة حسب ما تبنيه.

ما هو Instagram Graph API؟

Instagram Graph API هو الـ API الرسمي الكامل لحسابات Instagram Business وCreator. وهو الطريقة الشرعية الوحيدة للوصول البرمجي إلى بيانات Instagram ووظائفه — كل شيء من نشر المحتوى إلى قراءة التحليلات إلى الرد على رسائل DM يمرّ عبره.

يغطّي Graph API ستة مجالات قدرات رئيسية:

  • إدارة المحتوى — إنشاء ونشر واسترجاع المنشورات وReels والStories والكاروسيلات نيابةً عن حساب تجاري
  • تحليلات الوسائط — قراءة مرّات الظهور والوصول والتفاعل وبيانات الجمهور للوسائط الفردية والمقاييس على مستوى الحساب
  • التعليقات — قراءة التعليقات على المنشورات، والرد عليها، وحذفها، وإخفاءها
  • البحث بالوسوم — البحث عن المنشورات العامة بالوسم (مع حدود معدل صارمة)
  • الإشارات — اكتشاف عند ذِكر حسابك التجاري أو الإشارة إليه من حسابات أخرى في منشورات أو ستوريات
  • الرسائل المباشرة — استقبال وإرسال رسائل DM، ومعالجة الردود على الستوري وإشارات الستوري (هذه هي مجموعة "Messaging API" الفرعية)

جميع هذه الستة جزء من Graph API نفسه. عنوان URL الأساسي ونظام المصادقة وعملية App Review ونوع الرمز متطابقة عبرها جميعاً. تكمن الاختلافات في نقاط النهاية التي تستدعيها، والصلاحيات التي تطلبها، وحقول webhook التي تشترك فيها.

ما هو "Instagram Messaging API" تحديداً؟

عندما تشير Meta (ومعظم التوثيقات الخارجية) إلى "Instagram Messaging API" أو "Messenger API for Instagram"، فإنها تعني المجموعة الفرعية من Graph API التي تُمكّن:

  • استقبال رسائل DM — أحداث webhook عند إرسال المستخدمين رسالة مباشرة إلى حسابك التجاري
  • إرسال رسائل DM — استدعاء POST /{ig-user-id}/messages لإرسال رد إلى IGSID المستخدم
  • الردود على الستوري — أحداث webhook عند ردّ المستخدمين على ستوريك عبر DM (تصل مع message.reply_to.story)
  • إشارات الستوري — أحداث webhook عند الإشارة إلى حسابك في ستوريهم (تصل كحدث إحالة)
  • تفاعلات الإيموجي — أحداث webhook عند تفاعل المستخدمين مع إحدى رسائلك
  • إيصالات القراءة — أحداث webhook عند قراءة المستخدمين لرسائلك

هذه مجموعة فرعية مركّزة، خاصة برسائل DM فقط، من بين ما يستطيع Graph API الكامل فعله. تتطلّب صلاحيات رسائل محدّدة (instagram_manage_messages)، واشتراكات webhook محدّدة (messages، messaging_referrals)، ونقطة نهاية إرسال خاصة بها. لكنها تعمل على نفس البنية التحتية، ونفس المصادقة، ونفس التطبيق مثل كل شيء آخر.

مخطط فِن: Instagram Graph API هو الدائرة الخارجية الكبيرة. Instagram Messaging API دائرة أصغر محتواة بالكامل داخلها. كل قدرة في Messaging API هي جزء من Graph API. لكن Graph API يملك قدرات كثيرة ليست جزءاً من Messaging API (نشر المحتوى، التحليلات، البحث بالوسوم، إلخ.).

خريطة كاملة لنقاط النهاية: Graph API مقابل Messaging API

إليك خريطة كاملة لنقاط نهاية Instagram Graph API، مُصنّفة حسب ما إذا كانت Graph-only، أو Messaging-only (المجموعة الفرعية لـ "Messaging API")، أو تنطبق على كليهما:

📊 التحليلات / Insights — Graph API فقط
GET/{ig-user-id}?fields=followers_count,media_count,...
GET/{ig-user-id}/insights?metric=impressions&period=day
GET/{media-id}/insights?metric=reach,impressions
📸 نشر المحتوى — Graph API فقط
POST/{ig-user-id}/media (create container)
POST/{ig-user-id}/media_publish (publish container)
GET/{ig-user-id}/media (list posts)
💬 التعليقات — Graph API فقط
GET/{media-id}/comments
POST/{media-id}/comments (reply to comment)
POST/{comment-id}?hidden=true (hide comment)
🔍 البحث بالوسوم — Graph API فقط
GET/ig_hashtag_search?q=sunset&user_id={id}
GET/{hashtag-id}/top_media
💌 الرسائل المباشرة — Messaging API (مجموعة فرعية من Graph API)
POST/{ig-user-id}/messages (send DM to user)
GET/{ig-user-id}/conversations (list DM threads)
GET/{conversation-id}/messages (read thread)
🔗 معلومات الحساب — يستخدمها كلاهما
GET/me?fields=id,name,instagram_business_account
GET/{ig-user-id}?fields=id,name,username,biography

الصلاحيات: ما تحتاجه لكل قدرة

الصلاحيات هي أوضح طريقة للتمييز بين ما يتطلّبه "Messaging API" وما يحتاجه بقية Graph API. كل صلاحية تتطلّب App Review للاستخدام الإنتاجي خارج نطاق حسابات الاختبار.

الصلاحيةالفئةما تُمكّن منه
instagram_manage_messages Messaging API استقبال أحداث webhook الخاصة بـ DM. إرسال ردود DM عبر /{ig-user-id}/messages. الوصول إلى سجل المحادثات. مطلوبة لكل أتمتة DM.
pages_messaging Messaging API الاشتراك في أحداث webhook واستقبالها عبر صفحة Facebook المرتبطة. بدون هذه، لا تُطلَق webhooks الخاصة برسائل Instagram DM بصرف النظر عن الصلاحيات الأخرى.
pages_read_engagement كلاهما قراءة المعلومات الأساسية حول صفحة Facebook المرتبطة وحساب Instagram. مطلوبة من قِبل ميزات الرسائل وGraph API للتحقق من الحساب.
instagram_manage_insights Graph API قراءة بيانات التحليلات على مستوى الحساب والوسائط بما في ذلك مرّات الظهور والوصول والتفاعل وديموغرافيا المتابعين. للوحات التحليلات وأدوات التقارير.
instagram_content_publish Graph API إنشاء ونشر المنشورات وReels والStories والكاروسيلات نيابةً عن حساب تجاري. لأدوات جدولة ونشر المحتوى.
instagram_manage_comments Graph API قراءة التعليقات على المنشورات والرد عليها وإخفائها وحذفها. لأدوات إدارة التعليقات وأتمتة comment-to-DM (تحتاج أيضاً إلى instagram_manage_messages لخطوة إرسال DM).
instagram_basic Graph API قراءة معلومات الملف الشخصي الأساسية وقائمة المنشورات. تُدرَج غالباً كصلاحية أساسية إلى جانب صلاحيات أكثر تخصصاً لمعظم حالات استخدام Graph API.

اشتراكات webhook: الرسائل مقابل كل شيء آخر

اشتراكات حقول webhook هي حيث يتباعد Messaging API وبقية Graph API بأوضح صورة. تمرّ جميع الاشتراكات عبر إعدادات Instagram Webhooks في تطبيق Facebook الخاص بك، لكن الحقول التي تشترك فيها هي ما يحدّد الأحداث التي تستقبلها:

Instagram webhook subscription fields — messaging vs graph
// ── MESSAGING API WEBHOOK FIELDS ───────────────────────────────────────── messages // DMs received, story replies, quick replies, media DMs messaging_referrals // Story mentions (user tags your account in their story) messaging_optins // Opt-in events for recurring notification widgets // ── NON-MESSAGING GRAPH API WEBHOOK FIELDS ─────────────────────────────── mentions // When your account is @mentioned in another account's caption/comment comments // Comments on your posts (for comment management + comment-to-DM triggers) live_comments // Comments on live videos story_insights // Story analytics events // ── CRITICAL DISTINCTION ───────────────────────────────────────────────── // Story REPLIES (user DMs a reply to your story) → "messages" field // Story MENTIONS (user tags you in their story) → "messaging_referrals" field // @mentions in captions/comments → "mentions" field (non-messaging)

التداخل الأكثر إثارة للالتباس على الإطلاق: الأحداث المتعلّقة بالستوري تنقسم بين حقلَي webhook مختلفَين. ردّ مستخدم على ستوريك هو حدث رسائل (حقل messages). إشارة مستخدم إلى حسابك في ستوريه الخاص هي حدث إحالة (حقل messaging_referrals). إشارة حساب إليك في تعليق توضيحي هي حدث غير متعلق بالرسائل (حقل mentions). ثلاثة حقول webhook مختلفة لثلاث تفاعلات تبدو متشابهة سطحياً.

واجهة Instagram API القديمة المُهملة — ما كانت ولماذا تهمّ

سؤال Stack Overflow من عام 2019 الذي يظهر كثيراً عند هذا الاستعلام كان يقارن بين شيئَين لا يوجدان بنفس الصورة اليوم: "Instagram API" (مُهمَل بالكامل الآن) و"Instagram Graph API" (الحالي). فهم هذا التاريخ يوضّح لماذا كثير من الإجابات على الإنترنت خاطئة.

أُهملت Legacy Instagram API بالكامل في مارس 2020. أي تكامل لا يزال يستخدمها معطّل منذ سنوات. أي درس تعليمي أو إجابة على Stack Overflow من قبل 2020 تناقش "Instagram API" مقابل "Instagram Graph API" تصف مقارنة لم تعد موجودة. الحالة الراهنة: لا يوجد سوى Instagram Graph API (مع Messaging API كمجموعة فرعية). لا توجد "Instagram API" منفصلة لمقارنته بها.
Timeline: Instagram API history
// 2012 — Instagram API launched (the "old" API) // Base URL: api.instagram.com, OAuth-based, allowed personal account access // Could: read posts, search hashtags, get followers (for your own account) // 2018 — Instagram Graph API launched as replacement // Base URL: graph.facebook.com, uses Facebook OAuth, business accounts only // Added: analytics, content publishing, comments management // 2020 (March) — Legacy Instagram API fully shut down // All api.instagram.com endpoints stopped working // Only graph.facebook.com works from this point forward // 2020 (ongoing) — Instagram Messaging API (Messenger API for Instagram) // DM endpoints added to the Graph API // Uses graph.facebook.com/v21.0/{ig-user-id}/messages // Today: One API. graph.facebook.com. Multiple capability subsets. // "Messaging API" = DM subset. "Graph API" = all capabilities including DMs.

مصفوفة القرار: ماذا تستخدم لحالة استخدامك

بوت دردشة DM / مُجيب تلقائي
استقبال رسائل DM عبر webhook، وإرسال الردود، ومعالجة الردود وإشارات الستوري. الصلاحيات: instagram_manage_messages، pages_messaging. حقول webhook: messages، messaging_referrals.
Messaging API
لوحة تحليلات
قراءة مرّات الظهور والوصول وعدد المتابعين وأداء الوسائط على مستوى الحساب. الصلاحيات: instagram_manage_insights، instagram_basic.
Graph API
جدولة / نشر المحتوى
إنشاء ونشر المنشورات وReels والStories برمجياً. الصلاحيات: instagram_content_publish، instagram_basic.
Graph API
أداة إدارة التعليقات
قراءة التعليقات على المنشورات والرد عليها، وإخفاء البريد المزعج. حقل webhook: comments. الصلاحيات: instagram_manage_comments.
Graph API
أتمتة comment-to-DM
اكتشاف تعليق بكلمة مفتاحية، ثم إرسال DM لكاتب التعليق. تحتاج إلى كليهما: comments webhook (Graph API) + إرسال الرسائل (Messaging API). الصلاحيات: instagram_manage_comments + instagram_manage_messages.
كلاهما
منصة إدارة Instagram كاملة
كل القدرات: النشر، التحليلات، رسائل DM، التعليقات، البحث بالوسوم. كل الصلاحيات. حقول webhook متعددة.
كلاهما
أتمتة DM للتجارة الإلكترونية
استقبال رسائل DM لنوايا الشراء، وإرسال روابط المنتجات، وردود تتبّع الطلبات. حالة استخدام صرفة لـ Messaging API.
Messaging API
جمع UGC (إشارات الستوري)
اكتشاف إشارة المستخدمين إلى علامتك في ستورياتهم، وتنزيل الوسائط. Messaging API لـ webhook الإشارة + Graph API للوسائط.
كلاهما
FAQ

أسئلة شائعة

هل Instagram Messaging API واجهة منفصلة عن Instagram Graph API؟
لا. Instagram Messaging API مجموعة فرعية من نقاط النهاية والصلاحيات واشتراكات webhook ضمن Instagram Graph API. كلاهما يستخدم نفس عنوان URL الأساسي (graph.facebook.com/v21.0)، ونفس نظام المصادقة، ونفس إعداد تطبيق Facebook. "Instagram Messaging API" هو اسم منتج Meta للقدرات المخصّصة لرسائل DM ضمن إطار Graph API الأوسع.
ما الصلاحيات التي أحتاجها لرسائل Instagram DM مقابل تحليلات Instagram؟
رسائل DM (Messaging API): instagram_manage_messages + pages_messaging + pages_read_engagement. التحليلات (Graph API): instagram_manage_insights + instagram_basic. نشر المحتوى (Graph API): instagram_content_publish + instagram_basic. التعليقات (Graph API): instagram_manage_comments. كلها تتطلّب App Review للاستخدام الإنتاجي.
ما هي Instagram API القديمة وهل لا تزال متاحة؟
Instagram API القديمة (Legacy Instagram API) أُطلقت عام 2012 واستخدمت عنوان URL الأساسي api.instagram.com. سمحت بالوصول إلى الحسابات الشخصية واستخدمت OAuth خاصاً بـ Instagram. أُغلقت بالكامل في مارس 2020 ولم تعد تعمل. يجب على جميع تكاملات Instagram الحالية استخدام Instagram Graph API (graph.facebook.com). أي درس تعليمي يشير إلى "api.instagram.com" يصف نظاماً معطّلاً ومُهملاً.
ما حقول webhook التي أشترك فيها لرسائل Instagram DM؟
لرسائل DM والردود على الستوري: حقل messages. لإشارات الستوري (عند الإشارة إلى حسابك في ستوري المستخدمين): حقل messaging_referrals. لإشارات @ في التعليقات التوضيحية للمنشورات/التعليقات: حقل mentions (غير متعلق بالرسائل، Graph API). للتعليقات على المنشورات: حقل comments (Graph API). اشترك في كل الحقول التي تحتاجها من إعدادات Instagram Webhooks في تطبيق Facebook الخاص بك.
هل أحتاج إلى تطبيقَي Facebook مختلفَين لميزات Graph API الخاصة بالرسائل وغير الرسائل؟
لا — تطبيق Facebook واحد يتولّى كل قدرات Instagram Graph API. تطلب صلاحيات مختلفة لميزات مختلفة (instagram_manage_messages لرسائل DM، وinstagram_manage_insights للتحليلات، إلخ.)، لكنه نفس إعداد التطبيق. ستستخدم App Secret واحداً للتحقق من HMAC، وعنوان webhook واحداً لكل أحداث Instagram، ومجموعة واحدة من Page Access Tokens لكل حساب. الاختلاف فقط في الصلاحيات التي تطلبها ونقاط النهاية التي تستدعيها.
ما نقطة نهاية Instagram Send API لرسائل DM؟
نقطة النهاية هي POST /v21.0/{ig-user-id}/messages تُستدعى على graph.facebook.com. الـ ig-user-id هو المعرّف الرقمي لحساب Instagram Business الخاص بك (وهو أيضاً قيمة entry[0].id في webhooks الواردة). جسم الطلب: {"recipient": {"id": "USER_IGSID"}, "message": {"text": "your reply"}}. تتم المصادقة باستخدام Page Access Token يملك صلاحية instagram_manage_messages.
برنامج تعليمي
استقبل رسائل Instagram DM على خادمك
إعداد Messaging API الكامل — الصلاحيات، إعداد التطبيق، كود webhook، IGSID، Send API. ابنِها الآن.
تقني
Webhooks الرد على الستوري
حقول webhook الخاصة بالرسائل للردود على الستوري مقابل إشارات الستوري — حمولات دقيقة وكود توجيه.
تجارة إلكترونية
أتمتة Instagram DM للتجارة الإلكترونية
ما يمكنك بناؤه بمجرد أن تفهم الـ API — تكامل Shopify، اكتشاف النوايا، توصيات GPT-4o.
جاهز للبناء؟

طبقة webhook الخاصة بـ Messaging API،
متكفَّل بها لك.

الآن وقد عرفت أن Messaging API مجموعة فرعية من Graph API، الخطوة التالية هي استقبال تلك الأحداث على خادمك. تتولّى SocialHook التحقق من HMAC، وتحليل الحمولة الخام، وتوحيد صيغة الأحداث — كل DM، وكل ردّ على الستوري، وكل إشارة في الستوري تصل إلى نقطة نهايتك بصيغة JSON نظيفة.

اربط Instagram مجاناً ← اقرأ التوثيق
لا حاجة لبطاقة ائتمان · 50 دولاراً/شهر بعد التجربة · Instagram + Messenger + WhatsApp