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

TL;DR

يتيح Instagram Graph API للمطورين إدارة حسابات إنستغرام للأعمال والمبدعين برمجيًا. يستخدم مصادقة فيسبوك لتسجيل الدخول (Facebook Login OAuth 2.0)، ونقاط نهاية تعتمد على GraphQL لنشر المحتوى، والإحصاءات، والتعليقات، والمراسلة، مع حدود معدل تبلغ 200 استدعاء في الساعة لكل تطبيق. يغطي هذا الدليل إعداد المصادقة، ونشر المحتوى، واسترداد الإحصاءات، وإدارة التعليقات، واستراتيجيات التكامل في بيئة الإنتاج.

مقدمة

يستخدم إنستغرام أكثر من 2 مليار مستخدم نشط شهريًا، مع أكثر من 200 مليون شركة تستخدم حسابات إنستغرام للأعمال. بالنسبة للمطورين الذين ينشئون أدوات إدارة وسائل التواصل الاجتماعي، ومنصات التحليلات، أو تكاملات التجارة الإلكترونية، يعد تكامل Instagram Graph API ضروريًا للوصول إلى هذا الجمهور الهائل.

الواقع هنا: مدراء وسائل التواصل الاجتماعي الذين يديرون أكثر من 10 حسابات يخسرون 20-30 ساعة أسبوعيًا في النشر اليدوي، والردود على التعليقات، وتجميع التحليلات. يقوم تكامل Instagram API القوي بأتمتة نشر المحتوى، وإدارة التعليقات، وتحليل المشاعر، والإبلاغ عن الأداء.

يوضح هذا الدليل عملية تكامل Instagram Graph API بالكامل. ستتعلم مصادقة فيسبوك لتسجيل الدخول، ونشر المحتوى، وإحصاءات الوسائط، وإدارة التعليقات، وتكامل الـ Webhook، واستراتيجيات النشر في بيئة الإنتاج. بحلول النهاية، سيكون لديك تكامل إنستغرام جاهز للإنتاج.

ما هو Instagram Graph API؟

يوفر Instagram Graph API وصولاً برمجيًا إلى حسابات إنستغرام للأعمال والمبدعين من خلال Facebook Graph API. يتعامل الـ API مع:

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

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

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

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

يستخدم إنستغرام هيكل Facebook Graph API:

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

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

يصدر فيسبوك إصدارات جديدة ربع سنوية. استهدف دائمًا أحدث إصدار مستقر.

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

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

قبل الوصول إلى الـ API:

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

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

ربط إنستغرام بصفحة فيسبوك:

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

ملاحظة: لا يمكن لحسابات إنستغرام الشخصية استخدام Graph API. قم بالتحويل إلى حساب أعمال أو منشئ محتوى في إعدادات إنستغرام.

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

إنشاء رمز وصول المستخدم:

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;

// Build authorization URL
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()}`;
};

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

الخطوة 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;
};

// Usage
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;
};

// Usage
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();
};

// Usage
const account = await instagramRequest(`/me`);
console.log(`Instagram Account: ${account.username}`);

نشر المحتوى

نشر صورة

نشر صورة على إنستغرام:

const publishPhoto = async (igAccountId, photoData) => {
  // Step 1: Create media container
  const containerResponse = await instagramRequest(`/${igAccountId}/media`, {
    method: 'POST',
    image_url: photoData.imageUrl,
    caption: photoData.caption,
    location_id: photoData.locationId, // Optional
    is_carousel_item: 'false'
  });

  const creationId = containerResponse.id;

  // Step 2: Publish the media
  const publishResponse = await instagramRequest(`/${igAccountId}/media_publish`, {
    method: 'POST',
    creation_id: creationId
  });

  return publishResponse;
};

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

console.log(`Published media ID: ${post.id}`);

نشر فيديو

نشر فيديو على إنستغرام:

const publishVideo = async (igAccountId, videoData) => {
  // Step 1: Create media container
  const containerResponse = await instagramRequest(`/${igAccountId}/media`, {
    method: 'POST',
    video_url: videoData.videoUrl,
    cover_url: videoData.coverUrl, // Optional thumbnail
    caption: videoData.caption,
    media_type: 'REELS', // or 'VIDEO' for feed
    share_to_feed: 'true' // For reels
  });

  const creationId = containerResponse.id;

  // Wait for video processing (poll until status is EXPIRED or FINISHED)
  await waitForVideoProcessing(creationId);

  // Step 2: Publish the media
  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 = [];

  // Step 1: Create each carousel item
  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);
  }

  // Step 2: Create carousel container with children
  const carouselContainerResponse = await instagramRequest(`/${igAccountId}/media`, {
    method: 'POST',
    media_type: 'CAROUSEL',
    children: children.join(','),
    caption: carouselData.caption
  });

  const creationId = carouselContainerResponse.id;

  // Step 3: Publish the carousel
  const publishResponse = await instagramRequest(`/${igAccountId}/media_publish`, {
    method: 'POST',
    creation_id: creationId
  });

  return publishResponse;
};

// Usage
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: 'عرض توضيحي' }
  ]
});

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

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

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

جلب الوسائط المنشورة:

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;
};

// Usage
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;
};

// Usage
const insights = await getMediaInsights('17890000000000000');
insights.data.forEach(metric => {
  console.log(`${metric.name}: ${metric.values[0].value}`);
});

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

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

جلب تحليلات الحساب المجمعة:

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;
};

// Usage - Get last 30 days of metrics
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}`);
  });
});

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

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

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

جلب التعليقات على الوسائط:

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

  return response;
};

// Usage
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;
};

// Usage
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;
};

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

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

إزالة التعليقات غير المرغوب فيها أو غير اللائقة:

const deleteComment = async (commentId) => {
  await instagramRequest(`/${commentId}`, {
    method: 'DELETE'
  });

  console.log('تم حذف التعليق');
};

الـ Webhooks

تكوين الـ Webhooks

إعداد الـ Webhooks لإشعارات في الوقت الفعلي:

const subscribeToWebhooks = async (appId, pageId, accessToken) => {
  // Subscribe to Instagram events
  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();

// Verify webhook subscription
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('فشل التحقق');
  }
});

// Handle webhook events
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}`);

  // Auto-reply or moderate
  if (isSpam(data.text)) {
    await hideComment(data.id);
  }
}

حقول الـ Webhook

تحديد المعدل

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

يفرض Instagram Graph API ما يلي:

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

تؤدي تجاوز الحدود إلى استجابة HTTP 400 مع رمز خطأ فرعي 613.

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

1. تخزين الاستجابات مؤقتًا - لا تسترجع البيانات غير المتغيرة مرة أخرى
2. تجميع الطلبات - استخدم توسيع الحقول لتقليل الاستدعاءات
3. استخدم الـ Webhooks - تحديثات في الوقت الفعلي بدلاً من الاستقصاء (polling)
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. التحقق من أن عنوان URL للصورة متاح للجمهور (لا يتطلب مصادقة)
2. التحقق من تنسيق الصورة (JPEG, PNG) وحجمها (أقل من 8 ميغابايت)
3. التأكد من أن الفيديو بتنسيق MP4، وحجمه أقل من 1 جيجابايت، ومدته أقل من 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، ثم المصادقة عبر تسجيل الدخول بفيسبوك مع الأذونات المطلوبة.

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

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

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

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

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

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

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

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

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

نعم، يمكن نشر القصص باستخدام نفس سير عمل نشر المحتوى مثل منشورات الخلاصة.

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

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

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

نعم، استخدم Comments API لنشر الردود. تستخدم العديد من العلامات التجارية هذا للردود الآلية لخدمة العملاء.