كيفية استخدام Instagram Graph API في عام 2026

TL;DR

يتيح Instagram Graph API للمطورين أتمتة إدارة حسابات إنستغرام للأعمال والمبدعين برمجياً: مصادقة OAuth 2.0، نشر الصور والفيديوهات، جلب الإحصاءات، إدارة التعليقات، والتكامل مع Webhooks—all مع حد معدل 200 استدعاء/ساعة لكل تطبيق. هذا الدليل عملي يشرح خطوة بخطوة: إعداد المصادقة، نشر المحتوى، استرداد الإحصاءات، إدارة التعليقات، تكامل Webhook، واستراتيجيات الإنتاج.

جرّب Apidog اليوم

💡 Apidog يبسط اختبار تكامل الـ API: تحقق من نقاط نهاية إنستغرام لديك، اختبر تدفقات OAuth، اعرض استجابات الـ API، وصحح أخطاء النشر—all في مساحة عمل واحدة. استورد مواصفات الـ API، أنشئ استجابات وهمية، وشارك سيناريوهات الاختبار مع فريقك.

ما هو Instagram Graph API؟

يقدم Instagram Graph API وصولاً كاملًا برمجياً لحسابات الأعمال والمبدعين عبر Facebook Graph API. المهام الأساسية:

• نشر الصور، الفيديوهات، الريلز، والمنشورات الدوارة
• جلب الإحصاءات وتحليلات الوسائط
• إدارة التعليقات والإشارات
• دعم الرسائل المباشرة (عبر Instagram Graph API + Messenger Platform)
• تتبع الهاشتاغات والإشارات
• إدارة القصص
• دعم التسوق ووضع علامات المنتجات

الميزات الرئيسية

الميزة	الوصف
Graph-based API	الوصول إلى الموارد المستندة إلى العقد
OAuth 2.0	مصادقة تسجيل الدخول عبر فيسبوك
Webhooks	إشعارات في الوقت الفعلي للتعليقات والإشارات
Rate Limiting	200 استدعاء/ساعة لكل تطبيق
Content Publishing	الصور، الفيديو، الريلز، المنشورات الدوارة
Insights	مقاييس التفاعل، الوصول، الانطباعات
Moderation	إدارة التعليقات، الإشارات، الرسائل

متطلبات الحساب

نوع الحساب	وصول الـ API
حساب الأعمال	وصول كامل للـ API
حساب المبدع	وصول كامل للـ API
حساب شخصي	لا يوجد وصول للـ API
حساب خاص	إحصاءات محدودة

نظرة عامة على معمارية الـ API

يعتمد على Facebook Graph API:

https://graph.facebook.com/v18.0/

مقارنة بين إصدارات الـ API

الإصدار	الحالة	تاريخ الانتهاء	حالة الاستخدام
v18.0	الحالي	مارس 2026	جميع التكاملات الجديدة
v17.0	مهمل	يناير 2026	التكاملات الحالية
v16.0	متقاعد	انتهت صلاحيته	لا تستخدم

دائماً استهدف أحدث إصدار.

---

البدء: إعداد المصادقة

الخطوة 1: إنشاء حساب مطور فيسبوك

1. زر بوابة مطوري فيسبوك
2. سجل الدخول بحسابك على فيسبوك
3. أنشئ تطبيق فيسبوك (النوع: أعمال)
4. أضف منتج Instagram Graph API

الخطوة 2: ربط حساب إنستغرام للأعمال

1. اذهب لإعدادات صفحة فيسبوك > إنستغرام
2. اختر ربط الحساب
3. سجل دخول إنستغرام ووافق على الصلاحيات
4. تأكد من ربط حساب إنستغرام للأعمال

ملاحظة: حسابات إنستغرام الشخصية لا تدعم الـ API، يجب التحويل إلى "أعمال" أو "منشئ محتوى".

الخطوة 3: الحصول على رموز الوصول

أنشئ رابط مصادقة OAuth:

const FB_APP_ID = process.env.FB_APP_ID;
const FB_APP_SECRET = process.env.FB_APP_SECRET;
const FB_REDIRECT_URI = process.env.FB_REDIRECT_URI;

// إنشاء رابط المصادقة
const getAuthUrl = (state) => {
  const params = new URLSearchParams({
    client_id: FB_APP_ID,
    redirect_uri: FB_REDIRECT_URI,
    scope: 'instagram_basic,instagram_content_publish,instagram_manage_comments,instagram_manage_insights,pages_read_engagement',
    state: state
  });
  return `https://www.facebook.com/v18.0/dialog/oauth?${params.toString()}`;
};

الأذونات المطلوبة

الإذن	الوصف
instagram_basic	معلومات الملف وقائمة الوسائط
instagram_content_publish	نشر الصور والفيديو والمنشورات الدوارة
instagram_manage_comments	قراءة/كتابة التعليقات
instagram_manage_insights	الوصول لبيانات التحليلات
pages_read_engagement	وصول الصفحة للنشر
pages_manage_posts	النشر على الصفحة المرتبطة

الخطوة 4: استبدال الرمز برمز طويل الأمد

استبدل الرمز قصير الأمد (ساعة) برمز طويل (60 يوم):

const exchangeForLongLivedToken = async (shortLivedToken) => {
  const response = await fetch(
    `https://graph.facebook.com/v18.0/oauth/access_token?` +
    `grant_type=fb_exchange_token&` +
    `client_id=${FB_APP_ID}&` +
    `client_secret=${FB_APP_SECRET}&` +
    `fb_exchange_token=${shortLivedToken}`
  );
  const data = await response.json();
  return data;
};

// الاستخدام
const longLivedToken = await exchangeForLongLivedToken(shortLivedToken);
console.log(`Token expires: ${new Date(longLivedToken.expires_at * 1000)}`);

الخطوة 5: الحصول على معرف حساب إنستغرام للأعمال

const getInstagramAccountId = async (pageId, accessToken) => {
  const response = await fetch(
    `https://graph.facebook.com/v18.0/${pageId}?fields=instagram_business_account&access_token=${accessToken}`
  );
  const data = await response.json();
  return data.instagram_business_account.id;
};

// الاستخدام
const igAccountId = await getInstagramAccountId('12345678', accessToken);
console.log(`Instagram Account ID: ${igAccountId}`);

الخطوة 6: إجراء استدعاءات API مصادق عليها

عميل API قابل لإعادة الاستخدام:

const IG_BASE_URL = 'https://graph.facebook.com/v18.0';

const instagramRequest = async (endpoint, params = {}) => {
  const url = new URL(`${IG_BASE_URL}${endpoint}`);
  url.searchParams.append('access_token', process.env.INSTAGRAM_ACCESS_TOKEN);

  Object.entries(params).forEach(([key, value]) => {
    url.searchParams.append(key, value);
  });

  const response = await fetch(url.toString());

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Instagram API Error: ${error.error.message}`);
  }

  return response.json();
};

// الاستخدام
const account = await instagramRequest(`/me`);
console.log(`Instagram Account: ${account.username}`);

---

نشر المحتوى

نشر صورة

const publishPhoto = async (igAccountId, photoData) => {
  // 1. إنشاء حاوية الوسائط
  const containerResponse = await instagramRequest(`/${igAccountId}/media`, {
    method: 'POST',
    image_url: photoData.imageUrl,
    caption: photoData.caption,
    location_id: photoData.locationId, // اختياري
    is_carousel_item: 'false'
  });

  const creationId = containerResponse.id;

  // 2. نشر الوسائط
  const publishResponse = await instagramRequest(`/${igAccountId}/media_publish`, {
    method: 'POST',
    creation_id: creationId
  });

  return publishResponse;
};

// الاستخدام
const post = await publishPhoto({
  igAccountId: '17841400000000000',
  imageUrl: 'https://example.com/image.jpg',
  caption: 'متحمسون للإعلان عن منتجنا الجديد! 🚀 #إطلاق #ابتكار',
  locationId: '123456789' // اختياري
});
console.log(`Published media ID: ${post.id}`);

نشر فيديو

const publishVideo = async (igAccountId, videoData) => {
  // 1. إنشاء حاوية الوسائط
  const containerResponse = await instagramRequest(`/${igAccountId}/media`, {
    method: 'POST',
    video_url: videoData.videoUrl,
    cover_url: videoData.coverUrl, // صورة مصغرة اختيارية
    caption: videoData.caption,
    media_type: 'REELS', // أو VIDEO
    share_to_feed: 'true' // للريلز
  });

  const creationId = containerResponse.id;

  // انتظار معالجة الفيديو
  await waitForVideoProcessing(creationId);

  // 2. النشر
  const publishResponse = await instagramRequest(`/${igAccountId}/media_publish`, {
    method: 'POST',
    creation_id: creationId
  });

  return publishResponse;
};

const waitForVideoProcessing = async (creationId, maxAttempts = 30) => {
  for (let i = 0; i < maxAttempts; i++) {
    const status = await instagramRequest(`/${creationId}`);
    if (status.status_code === 'FINISHED') {
      return true;
    } else if (status.status_code === 'EXPIRED') {
      throw new Error('Video processing expired');
    }
    await new Promise(resolve => setTimeout(resolve, 2000));
  }
  throw new Error('Video processing timeout');
};

نشر منشور دوار (صور/فيديو متعددة)

const publishCarousel = async (igAccountId, carouselData) => {
  const children = [];
  // 1. إنشاء كل عنصر في الدوار
  for (const item of carouselData.items) {
    const containerResponse = await instagramRequest(`/${igAccountId}/media`, {
      method: 'POST',
      [item.type === 'video' ? 'video_url' : 'image_url']: item.url,
      caption: item.caption || '',
      is_carousel_item: 'true'
    });
    children.push(containerResponse.id);
  }

  // 2. إنشاء حاوية الدوار مع children
  const carouselContainerResponse = await instagramRequest(`/${igAccountId}/media`, {
    method: 'POST',
    media_type: 'CAROUSEL',
    children: children.join(','),
    caption: carouselData.caption
  });

  const creationId = carouselContainerResponse.id;

  // 3. النشر
  const publishResponse = await instagramRequest(`/${igAccountId}/media_publish`, {
    method: 'POST',
    creation_id: creationId
  });

  return publishResponse;
};

// الاستخدام
const carousel = await publishCarousel('17841400000000000', {
  caption: 'عرض المنتجات 2026',
  items: [
    { type: 'image', url: 'https://example.com/img1.jpg', caption: 'المنتج 1' },
    { type: 'image', url: 'https://example.com/img2.jpg', caption: 'المنتج 2' },
    { type: 'video', url: 'https://example.com/vid1.mp4', caption: 'عرض توضيحي' }
  ]
});

أنواع الوسائط

نوع الوسائط	البارامترات	حالة الاستخدام
IMAGE	image_url, caption	منشورات الصور
VIDEO	video_url, cover_url, caption	منشورات الفيديو
REELS	video_url, cover_url, caption, share_to_feed	الريلز
CAROUSEL	children (مصفوفة), caption	وسائط متعددة

---

استرداد الوسائط والإحصاءات

الحصول على وسائط المستخدم

const getUserMedia = async (igAccountId, limit = 25) => {
  const response = await instagramRequest(`/${igAccountId}/media`, {
    fields: 'id,caption,media_type,media_url,permalink,timestamp,like_count,comments_count',
    limit: limit.toString()
  });
  return response;
};

// الاستخدام
const media = await getUserMedia('17841400000000000');
media.data.forEach(item => {
  console.log(`${item.media_type}: ${item.caption}`);
  console.log(`Likes: ${item.like_count}, Comments: ${item.comments_count}`);
  console.log(`URL: ${item.permalink}`);
});

الحصول على إحصاءات الوسائط

const getMediaInsights = async (mediaId) => {
  const response = await instagramRequest(`/${mediaId}/insights`, {
    fields: 'impressions,reach,engagement,saved,video_views,profile_visits,follows'
  });
  return response;
};

// الاستخدام
const insights = await getMediaInsights('17890000000000000');
insights.data.forEach(metric => {
  console.log(`${metric.name}: ${metric.values[0].value}`);
});

مقاييس الإحصاءات المتاحة

المقياس	الوصف	أنواع الوسائط
impressions	إجمالي المشاهدات	الكل
reach	عدد الحسابات الفريدة	الكل
engagement	الإعجابات+التعليقات+الحفظ	الكل
saved	عدد مرات الحفظ	الكل
video_views	مشاهدات الفيديو (3+ ثوانٍ)	فيديو، ريلز
plays	إجمالي مرات تشغيل الفيديو	فيديو، ريلز
profile_visits	زيارات الملف الشخصي	الكل
follows	المتابعات من المنشور	الكل
comments	عدد التعليقات	الكل
like_count	عدد الإعجابات	الكل

الحصول على إحصاءات الحساب

const getAccountInsights = async (igAccountId, metricNames, since = null, until = null) => {
  const params = {
    metric: metricNames.join(','),
    period: 'day'
  };
  if (since) params.since = since;
  if (until) params.until = until;
  const response = await instagramRequest(`/${igAccountId}/insights`, params);
  return response;
};

// الاستخدام - آخر 30 يوم
const accountInsights = await getAccountInsights(
  '17841400000000000',
  ['impressions', 'reach', 'profile_views', 'email_contacts', 'website_clicks'],
  '2026-02-23',
  '2026-03-25'
);
accountInsights.data.forEach(metric => {
  console.log(`${metric.name}:`);
  metric.values.forEach(value => {
    console.log(`  ${value.end_time}: ${value.value}`);
  });
});

المقاييس على مستوى الحساب

المقياس	الوصف
impressions	إجمالي مشاهدات الملف والمحتوى
reach	عدد الحسابات الفريدة
profile_views	زيارات الملف الشخصي
website_clicks	نقرات الرابط في السيرة الذاتية
email_contacts	نقرات زر البريد الإلكتروني
phone_call_clicks	نقرات زر الهاتف
text_message_clicks	نقرات زر الرسائل النصية القصيرة
get_directions_clicks	نقرات العنوان للحصول على الاتجاهات
follower_count	إجمالي المتابعين
audience_city	مدن المتابعين
audience_country	بلدان المتابعين
audience_gender_age	التقسيم الديموغرافي

---

إدارة التعليقات

الحصول على التعليقات

const getMediaComments = async (mediaId, limit = 50) => {
  const response = await instagramRequest(`/${mediaId}/comments`, {
    fields: 'id,text,timestamp,username,hidden',
    limit: limit.toString()
  });
  return response;
};

// الاستخدام
const comments = await getMediaComments('17890000000000000');
comments.data.forEach(comment => {
  console.log(`@${comment.username}: ${comment.text}`);
  console.log(`Hidden: ${comment.hidden}`);
});

الرد على التعليقات

const replyToComment = async (mediaId, commentId, replyText) => {
  const response = await instagramRequest(`/${mediaId}/comments`, {
    method: 'POST',
    response_to: commentId,
    message: replyText
  });
  return response;
};

// الاستخدام
const reply = await replyToComment(
  '17890000000000000',
  '17900000000000000',
  'شكرا لاهتمامكم! تحقق من رسائلك المباشرة للحصول على التفاصيل.'
);
console.log(`Reply posted: ${reply.id}`);

إخفاء التعليقات

const hideComment = async (commentId) => {
  const response = await instagramRequest(`/${commentId}`, {
    method: 'POST',
    hide: 'true'
  });
  return response;
};

// الاستخدام
await hideComment('17900000000000000');
console.log('تم إخفاء التعليق');

حذف التعليقات

const deleteComment = async (commentId) => {
  await instagramRequest(`/${commentId}`, {
    method: 'DELETE'
  });
  console.log('تم حذف التعليق');
};

---

الـ Webhooks

تكوين الـ Webhooks

const subscribeToWebhooks = async (appId, pageId, accessToken) => {
  // الاشتراك في أحداث Instagram
  const response = await fetch(
    `https://graph.facebook.com/v18.0/${appId}/subscriptions`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        object: 'instagram',
        callback_url: 'https://myapp.com/webhooks/instagram',
        verify_token: process.env.WEBHOOK_VERIFY_TOKEN,
        access_token: accessToken,
        fields: ['comments', 'mentions', 'message_reactions']
      })
    }
  );
  return response.json();
};

التعامل مع الـ Webhooks

const express = require('express');
const app = express();

// تحقق من الاشتراك
app.get('/webhooks/instagram', (req, res) => {
  const mode = req.query['hub.mode'];
  const token = req.query['hub.verify_token'];
  const challenge = req.query['hub.challenge'];
  if (mode === 'subscribe' && token === process.env.WEBHOOK_VERIFY_TOKEN) {
    console.log('تم التحقق من الـ Webhook');
    res.status(200).send(challenge);
  } else {
    res.status(403).send('فشل التحقق');
  }
});

// استقبال الأحداث
app.post('/webhooks/instagram', express.json(), async (req, res) => {
  const body = req.body;
  if (body.object !== 'instagram') {
    return res.status(404).send('غير موجود');
  }
  for (const entry of body.entry) {
    const igId = entry.id;
    const changes = entry.changes;
    for (const change of changes) {
      switch (change.field) {
        case 'comments':
          await handleNewComment(change.value);
          break;
        case 'mentions':
          await handleMention(change.value);
          break;
        case 'message_reactions':
          await handleReaction(change.value);
          break;
      }
    }
  }
  res.status(200).send('OK');
});

async function handleNewComment(data) {
  console.log(`تعليق جديد على الوسائط ${data.media_id}`);
  console.log(`من: ${data.from_id}`);
  console.log(`النص: ${data.text}`);
  // رد تلقائي أو إخفاء التعليق إذا كان سبام
  if (isSpam(data.text)) {
    await hideComment(data.id);
  }
}

حقول الـ Webhook

الحقل	المُشغّل
comments	تعليق جديد أو رد
mentions	المستخدم يذكر الحساب
message_reactions	رد فعل على القصة
story_status	الرد على القصة/مشاهدتها

---

تحديد المعدل

فهم حدود المعدل

• 200 استدعاء/ساعة لكل تطبيق (مشتركة بين جميع المستخدمين)
• Business Discovery: 200 استدعاء/ساعة لكل مستخدم
• نشر المحتوى: حدود حسب نوع الإجراء

تجاوز الحدود ينتج عنه خطأ HTTP 400 برمز فرعي 613.

أفضل الممارسات لتحديد المعدل

1. تخزين الاستجابات مؤقتًا – لا تعيد جلب البيانات الثابتة.
2. تجميع الطلبات – استخدم توسيع الحقول لتقليل عدد الاستدعاءات.
3. استخدم الـ Webhooks – للحصول على التحديثات الفورية بدلاً من الاستقصاء الدوري.
4. تطبيق التراجع (backoff) – تراجع أسي عند استقبال أخطاء 429.

const makeRateLimitedRequest = async (endpoint, params = {}, maxRetries = 3) => {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await instagramRequest(endpoint, params);
      return response;
    } catch (error) {
      if (error.message.includes('429') && attempt < maxRetries) {
        const delay = Math.pow(2, attempt) * 1000;
        console.log(`تم تحديد المعدل. إعادة المحاولة خلال ${delay} مللي ثانية...`);
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw error;
      }
    }
  }
};

---

استكشاف المشكلات الشائعة وإصلاحها

مشكلة: انتهاء صلاحية رمز OAuth

الأعراض: ظهور خطأ "رمز وصول OAuth غير صالح".

الحلول:

1. نفذ تحديث الرمز قبل انتهاء فترة الـ 60 يوماً.
2. خزّن تاريخ انتهاء الرمز ونبه المستخدم قبل الانتهاء.
3. أعد مصادقة المستخدم في حالة انتهاء الصلاحية.

مشكلة: فشل نشر الوسائط

الأعراض: فشل النشر أو ظهور خطأ.

الحلول:

1. تحقق أن رابط الصورة متاح للجمهور.
2. تحقق من نوع الصورة (JPEG/PNG) والحجم (< 8MB).
3. للفيديو: تأكد من MP4، أقل من 1GB وأقل من 90 ثانية.
4. انتظر اكتمال معالجة الفيديو قبل النشر.

مشكلة: الإحصاءات غير متاحة

الأعراض: Insights API يرجع بيانات فارغة.

الحلول:

1. تحقق أن الحساب "أعمال" أو "منشئ محتوى".
2. انتظر 24-48 ساعة بعد النشر حتى تتوفر الإحصاءات.
3. تأكد من وجود تفاعل كافٍ على الحساب.

---

قائمة مراجعة النشر في بيئة الإنتاج

قبل الإطلاق:

• [ ] تحويل جميع الحسابات إلى "أعمال" أو "منشئ محتوى"
• [ ] OAuth 2.0 مع رموز طويلة الأمد
• [ ] تخزين الرموز بشكل آمن ومشفّر
• [ ] تطبيق التحديث التلقائي للرموز
• [ ] إعداد الـ Webhook على HTTPS
• [ ] تطبيق تحديد المعدل وقائمة انتظار للطلبات
• [ ] التعامل مع جميع أخطاء الـ API
• [ ] تسجيل جميع الاستدعاءات
• [ ] سير عمل إدارة المحتوى
• [ ] اختبار على أنواع حسابات متعددة

---

حالات الاستخدام الواقعية

أداة جدولة وسائل التواصل الاجتماعي

التحدي: نشر يدوي لـ 50+ حساب عميل

الحل: النشر المجدول عبر Instagram API

النتيجة: توفير 80% من الوقت، نشر منظم

خصائص التطبيق:

• تقويم محتوى مع جدولة بالسحب والإفلات
• نشر تلقائي للصور/الفيديو/الدوار
• اقتراحات هاشتاغ ذكية

أتمتة خدمة العملاء

التحدي: بطء في الرد على استفسارات العملاء

الحل: رد تلقائي على الأسئلة الشائعة باستخدام Webhook

النتيجة: متوسط استجابة 5 دقائق، رضا العملاء 90%

خصائص التطبيق:

• اكتشاف الكلمات الرئيسية (السعر، التوفر، الشحن)
• رد تلقائي بروابط المنتجات
• تصعيد الحالات المعقدة لوكلاء بشريين

---

الخلاصة

Instagram Graph API يمنحك وصولاً شاملاً لأتمتة إدارة ونشر وتحليل حسابات الأعمال والمبدعين. تذكر دائماً:

• مصادقة OAuth 2.0 مع رموز وصول لمدة 60 يوم
• نشر صور وفيديو وريلز ومنشورات دوارة
• Insights API لبيانات التفاعل والديموغرافيا
• Webhooks لمراقبة التعليقات والإشارات فورياً
• حد المعدل 200 استدعاء/ساعة يتطلب إدارة ذكية
• Apidog يبسط اختبار الـ API والتعاون الجماعي

---

قسم الأسئلة الشائعة

كيف أحصل على وصول إلى Instagram API؟

أنشئ حساب مطور فيسبوك، أنشئ تطبيق أعمال، أضف Instagram Graph API، ثم صادق عبر Facebook Login مع الأذونات المطلوبة.

هل يمكنني النشر على إنستغرام تلقائيًا؟

نعم، استخدم Content Publishing API لنشر الصور والفيديوهات والريلز والمنشورات الدوارة لحسابات الأعمال والمبدعين.

ما هي أنواع حسابات إنستغرام التي تدعم الـ API؟

فقط حسابات الأعمال والمبدعين لها وصول كامل. الحسابات الشخصية وصولها محدود أو معدوم.

كيف أحصل على التعليقات من إنستغرام؟

استخدم نقطة النهاية /{media-id}/comments لجلب التعليقات. يمكن استخدام Webhooks للإشعارات الفورية.

ما هي حدود معدل إنستغرام؟

200 استدعاء/ساعة لكل تطبيق. بعض النقاط لها حدود إضافية لكل مستخدم.

هل يمكنني نشر القصص عبر الـ API؟

نعم، بنفس سير عمل نشر منشورات الخلاصة.

كيف أصل إلى إحصاءات إنستغرام؟

اطلب إذن instagram_manage_insights أثناء المصادقة. استخدم نقطة نهاية Insights لجلب مقاييس الوسائط والحساب.

هل يمكنني الرد على التعليقات تلقائيًا؟

نعم، استخدم Comments API لنشر الردود تلقائيًا. كثير من العلامات التجارية تعتمد ذلك لخدمة العملاء.