2026'da Instagram Graph API Nasıl Kullanılır?

Kısaca

Instagram Graph API, geliştiricilerin Instagram İşletme ve İçerik Üreticisi hesaplarını programlı olarak yönetmelerini sağlar. İçerik yayınlama, analizler, yorumlar ve mesajlaşma için Facebook Girişi OAuth 2.0 kimlik doğrulamasını, GraphQL tabanlı uç noktaları kullanır ve uygulama başına saatte 200 çağrı hız sınırına sahiptir. Bu rehber, kimlik doğrulama kurulumunu, içerik yayınlamayı, analizleri almayı, yorum yönetimini ve üretim entegrasyon stratejilerini kapsar.

Giriş

Instagram'ın 2 milyardan fazla aylık aktif kullanıcısı ve 200 milyondan fazla işletme Instagram İşletme hesaplarını kullanmaktadır. Sosyal medya yönetim araçları, analiz platformları veya e-ticaret entegrasyonları geliştiren geliştiriciler için, bu devasa kitleye ulaşmak amacıyla Instagram Graph API entegrasyonu elzemdir.

Gerçek şu ki: 10'dan fazla hesabı yöneten sosyal medya yöneticileri, manuel gönderim, yorum yanıtları ve analiz derleme işlerine haftalık 20-30 saat harcıyor. Sağlam bir Instagram API entegrasyonu, içerik yayınlamayı, yorum denetimini, duygu analizini ve performans raporlamasını otomatikleştirir.

Bu rehber, eksiksiz Instagram Graph API entegrasyon sürecini adım adım anlatır. Facebook Girişi kimlik doğrulamasını, içerik yayınlamayı, medya analizlerini, yorum yönetimini, webhook entegrasyonunu ve üretim dağıtım stratejilerini öğreneceksiniz. Sonunda, üretime hazır bir Instagram entegrasyonuna sahip olacaksınız.

Instagram Graph API Nedir?

Instagram Graph API, Facebook Graph API aracılığıyla Instagram İşletme ve İçerik Üreticisi hesaplarına programlı erişim sağlar. API şunları yönetir:

• İçerik yayınlama (fotoğraflar, videolar, Reels, döngüsel gönderiler)
• Medya analizleri ve istatistikleri
• Yorum ve bahsetme yönetimi
• Doğrudan mesajlaşma (Instagram Graph API + Messenger Platform aracılığıyla)
• Hashtag ve bahsetme takibi
• Hikaye yönetimi
• Alışveriş ve ürün etiketleri

Temel Özellikler

Hesap Gereksinimleri

API Mimarisinin Genel Bakışı

Instagram, Facebook Graph API yapısını kullanır:

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

Karşılaştırılan API Sürümleri

Facebook, yeni sürümleri üç ayda bir yayınlar. Her zaman en son kararlı sürümü hedefleyin.

Başlarken: Kimlik Doğrulama Kurulumu

Adım 1: Facebook Geliştirici Hesabı Oluşturun

API'ye erişmeden önce:

1. Facebook Geliştiriciler Portalını ziyaret edin
2. Facebook hesabınızla giriş yapın
3. Bir Facebook Uygulaması oluşturun (tür: İşletme)
4. Instagram Graph API ürününü ekleyin

Adım 2: Instagram İşletme Hesabını Bağlayın

Instagram'ı Facebook Sayfasına bağlayın:

1. Facebook Sayfa Ayarları > Instagram'a gidin
2. Hesabı Bağla'ya tıklayın
3. Instagram'a giriş yapın ve yetkilendirin
4. Instagram İşletme hesabının bağlı olduğunu doğrulayın

Not: Kişisel Instagram hesapları Graph API'yi kullanamaz. Instagram Ayarlarından İşletme veya İçerik Üreticisi hesabına dönüştürün.

Adım 3: Erişim Belirteçlerini Alın

Kullanıcı Erişim Belirteci oluşturun:

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

Gerekli İzinler

Adım 4: Belirteci Uzun Ömürlü Belirteçle Değiştirin

Kısa ömürlü belirteçlerin süresi 1 saat içinde dolar. Uzun ömürlü belirteçle değiştirin (60 gün):

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

Adım 5: Instagram İşletme Hesabı Kimliğini Alın

Bağlı Instagram hesabını alın:

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

Adım 6: Kimliği Doğrulanmış API Çağrıları Yapın

Yeniden kullanılabilir API istemcisi oluşturun:

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

İçerik Yayınlama

Fotoğraf Yayınlama

Instagram'a fotoğraf gönderin:

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: 'Excited to announce our new product! 🚀 #launch #innovation',
  locationId: '123456789' // Optional
});

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

Video Yayınlama

Instagram'a video gönderin:

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

Döngüsel Gönderi Yayınlama (Birden Fazla Resim/Video)

Tek bir gönderide birden fazla medya öğesi yayınlayın:

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: 'Product showcase 2026',
  items: [
    { type: 'image', url: 'https://example.com/img1.jpg', caption: 'Product 1' },
    { type: 'image', url: 'https://example.com/img2.jpg', caption: 'Product 2' },
    { type: 'video', url: 'https://example.com/vid1.mp4', caption: 'Demo' }
  ]
});

Medya Türleri

Medya ve Analizleri Alma

Kullanıcı Medyasını Alma

Yayınlanmış medyayı alın:

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

Medya Analizlerini Alma

Belirli bir medya için analizleri alın:

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

Mevcut Analiz Metrikleri

Hesap Analizlerini Alma

Toplu hesap analizlerini alın:

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

Hesap Düzeyi Metrikleri

Yorum Yönetimi

Yorumları Alma

Medya üzerindeki yorumları alın:

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

Yorumlara Yanıtlama

Yorumlara yanıt gönderin:

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',
  'Thank you for your interest! Check your DM for details.'
);
console.log(`Reply posted: ${reply.id}`);

Yorumları Gizleme

Uygunsuz yorumları gizleyin:

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

  return response;
};

// Usage
await hideComment('17900000000000000');
console.log('Comment hidden');

Yorumları Silme

Spam veya uygunsuz yorumları kaldırın:

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

  console.log('Comment deleted');
};

Web Kancaları

Web Kancalarını Yapılandırma

Gerçek zamanlı bildirimler için web kancalarını ayarlayın:

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

Web Kancalarını İşleme

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 verified');
    res.status(200).send(challenge);
  } else {
    res.status(403).send('Verification failed');
  }
});

// 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('Not found');
  }

  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(`New comment on media ${data.media_id}`);
  console.log(`From: ${data.from_id}`);
  console.log(`Text: ${data.text}`);

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

Web Kancası Alanları

Hız Sınırlaması

Hız Sınırlarını Anlama

Instagram Graph API şunları uygular:

• Uygulama başına saatte 200 çağrı (tüm kullanıcılar arasında paylaşılır)
• İşletme Keşfi: Kullanıcı başına saatte 200 çağrı
• İçerik Yayınlama: Eylem türüne göre sınırlıdır

Sınırları aşmak, hata alt kodu 613 ile HTTP 400 ile sonuçlanır.

Hız Sınırlaması En İyi Uygulamaları

1. Yanıtları önbelleğe alın - Değişmeyen verileri yeniden çekmeyin
2. Toplu istekler yapın - Çağrıları azaltmak için alan genişletme kullanın
3. Web kancalarını kullanın - Yoklama yerine gerçek zamanlı güncellemeler alın
4. Gecikme uygulayın - 429 hatalarında üstel geri çekilme uygulayın

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(`Rate limited. Retrying in ${delay}ms...`);
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw error;
      }
    }
  }
};

Sık Karşılaşılan Sorunları Giderme

Sorun: OAuth Belirteci Süresi Doldu

Belirtiler: "Geçersiz OAuth erişim belirteci" hataları alınıyor.

Çözümler:

1. 60 günlük sona erme süresinden önce belirteç yenilemeyi uygulayın
2. Belirteç sona erme tarihini saklayın ve sona ermeden önce uyarı verin
3. Belirteç süresi dolarsa kullanıcıyı yeniden doğrulayın

Sorun: Medya Yayınlama Başarısız Oluyor

Belirtiler: Yayınlama hata döndürüyor.

Çözümler:

1. Resim URL'sinin herkese açık (kimlik doğrulama gerektirmeyen) olduğundan emin olun
2. Resim formatını (JPEG, PNG) ve boyutunu (<8MB) kontrol edin
3. Videonun MP4 formatında, <1GB ve <90 saniye olduğundan emin olun
4. Yayınlamadan önce video işlemesinin bitmesini bekleyin

Sorun: Analizler Mevcut Değil

Belirtiler: Analizler API'si boş veri döndürüyor.

Çözümler:

1. Hesabın İşletme veya İçerik Üreticisi (Kişisel değil) olduğunu doğrulayın
2. Analizlerin dolması için 24-48 saat bekleyin
3. Hesabın yeterli etkinliğe sahip olduğunu kontrol edin

Üretim Dağıtım Kontrol Listesi

Canlıya geçmeden önce:

• [ ] Tüm test hesaplarını İşletme/İçerik Üreticisi hesabına dönüştürün
• [ ] Uzun ömürlü belirteçlerle OAuth 2.0'ı uygulayın
• [ ] Belirteçleri şifreleme ile güvenli bir şekilde saklayın
• [ ] Otomatik belirteç yenilemeyi uygulayın
• [ ] Web kancası uç noktalarını HTTPS ile kurun
• [ ] Hız sınırlamasını ve istek kuyruğuna almayı ekleyin
• [ ] Kapsamlı hata işlemeyi uygulayın
• [ ] Tüm API çağrıları için günlük kaydı ekleyin
• [ ] İçerik denetimi iş akışları oluşturun
• [ ] Birden fazla hesap türüyle test edin

Gerçek Dünya Kullanım Durumları

Sosyal Medya Zamanlama Aracı

Bir pazarlama platformu gönderileri otomatikleştiriyor:

• Zorluk: 50'den fazla müşteri hesabına manuel gönderim
• Çözüm: Instagram API aracılığıyla planlanmış yayınlama
• Sonuç: %80 zaman tasarrufu, tutarlı gönderi takvimi

Temel uygulama:

• Sürükle-bırak zamanlamalı içerik takvimi
• Fotoğrafları, videoları, döngüsel gönderileri otomatik yayınlama
• İçeriğe dayalı hashtag önerileri

Müşteri Hizmetleri Otomasyonu

Bir e-ticaret markası yorum yanıtlarını otomatikleştiriyor:

• Zorluk: Müşteri sorularına yavaş yanıt verme
• Çözüm: Web kancası aracılığıyla sık sorulan sorulara otomatik yanıt
• Sonuç: Ortalama 5 dakikalık yanıt süresi, %90 memnuniyet

Temel uygulama:

• Anahtar kelime tespiti (fiyat, stok durumu, gönderim)
• Ürün bağlantılarıyla otomatik yanıt
• Karmaşık sorguları insan operatörlere yönlendirme

Sonuç

Instagram Graph API, Instagram İşletme ve İçerik Üreticisi hesabı özelliklerine kapsamlı erişim sağlar. Temel çıkarımlar:

• 60 günlük belirteçlerle Facebook Girişi OAuth 2.0 kimlik doğrulaması
• İçerik yayınlama fotoğrafları, videoları, Reels'leri, döngüsel gönderileri destekler
• Analizler API'si etkileşim, erişim ve demografik veriler sağlar
• Web kancaları gerçek zamanlı yorum ve bahsetme izlemeyi sağlar
• Uygulama başına saatte 200 çağrı hız sınırı dikkatli yönetim gerektirir
• Apidog, API testini ve ekip işbirliğini kolaylaştırır

Sıkça Sorulan Sorular

Instagram API'ye nasıl erişebilirim?

Bir Facebook Geliştirici hesabı oluşturun, bir İşletme uygulaması oluşturun, Instagram Graph API ürününü ekleyin ve gerekli izinlerle Facebook Girişi aracılığıyla kimlik doğrulayın.

Instagram'a otomatik olarak gönderi yapabilir miyim?

Evet, İşletme ve İçerik Üreticisi hesaplarına fotoğraf, video, Reels ve döngüsel gönderiler yayınlamak için İçerik Yayınlama API'sini kullanabilirsiniz.

Hangi tür Instagram hesapları API'yi destekler?

Yalnızca İşletme ve İçerik Üreticisi hesapları tam API erişimine sahiptir. Kişisel hesapların sınırlı veya hiç API erişimi yoktur.

Instagram'dan yorumları nasıl alırım?

Belirli bir medyadaki yorumları almak için Yorumlar uç noktasını (/{media-id}/comments) kullanın. Web kancaları gerçek zamanlı bildirimler sağlar.

Instagram hız sınırları nelerdir?

Instagram Graph API, uygulama başına saatte 200 çağrıya izin verir. Bazı uç noktaların ek kullanıcı başına sınırları vardır.

API aracılığıyla Hikayeler yayınlayabilir miyim?

Evet, Hikayeler akış gönderileriyle aynı içerik yayınlama akışı kullanılarak yayınlanabilir.

Instagram Analizlerine nasıl erişirim?

OAuth sırasında instagram_manage_insights iznini talep edin. Medya ve hesap için metrikleri almak üzere Analizler uç noktasını kullanın.

Yorumlara otomatik olarak yanıt verebilir miyim?

Evet, yanıtları göndermek için Yorumlar API'sini kullanın. Birçok marka bunu otomatik müşteri hizmetleri yanıtları için kullanır.