Comment utiliser l'API Graph Instagram en 2026 ?

En bref

L'API Graph d'Instagram permet aux développeurs de gérer les comptes Instagram Business et Creator par programmation. Elle utilise l'authentification OAuth 2.0 de Facebook Login, des points de terminaison basés sur GraphQL pour la publication de contenu, les statistiques, les commentaires et la messagerie, avec des limites de débit de 200 appels par heure par application. Ce guide couvre la configuration de l'authentification, la publication de contenu, la récupération des statistiques, la gestion des commentaires et les stratégies d'intégration en production.

Introduction

Instagram compte plus de 2 milliards d'utilisateurs actifs mensuels, avec plus de 200 millions d'entreprises utilisant des comptes Instagram Business. Pour les développeurs créant des outils de gestion des médias sociaux, des plateformes d'analyse ou des intégrations e-commerce, l'intégration de l'API Graph d'Instagram est essentielle pour atteindre cette audience massive.

Voici la réalité : les gestionnaires de médias sociaux gérant plus de 10 comptes perdent 20 à 30 heures par semaine en publications manuelles, réponses aux commentaires et compilation d'analyses. Une solide intégration de l'API Instagram automatise la publication de contenu, la modération des commentaires, l'analyse des sentiments et les rapports de performance.

Ce guide vous présente le processus complet d'intégration de l'API Graph d'Instagram. Vous apprendrez l'authentification Facebook Login, la publication de contenu, les statistiques des médias, la gestion des commentaires, l'intégration des webhooks et les stratégies de déploiement en production. À la fin, vous disposerez d'une intégration Instagram prête pour la production.

Qu'est-ce que l'API Graph d'Instagram ?

L'API Graph d'Instagram offre un accès par programmation aux comptes Instagram Business et Creator via l'API Graph de Facebook. L'API gère :

• Publication de contenu (photos, vidéos, Reels, carrousels)
• Statistiques et analyses des médias
• Gestion des commentaires et des mentions
• Messagerie directe (via l'API Graph d'Instagram + Plateforme Messenger)
• Suivi des hashtags et des mentions
• Gestion des Stories
• Achats et balises de produits

Fonctionnalités clés

Exigences du compte

Aperçu de l'architecture de l'API

Instagram utilise la structure de l'API Graph de Facebook :

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

Comparaison des versions de l'API

Facebook publie de nouvelles versions chaque trimestre. Visez toujours la dernière version stable.

Démarrage : Configuration de l'authentification

Étape 1 : Créer un compte développeur Facebook

Avant d'accéder à l'API :

1. Visitez le Portail des développeurs Facebook
2. Connectez-vous avec votre compte Facebook
3. Créez une application Facebook (type : Entreprise)
4. Ajoutez le produit API Graph d'Instagram

Étape 2 : Lier un compte Instagram Business

Connectez Instagram à une Page Facebook :

1. Allez dans Paramètres de la Page Facebook > Instagram
2. Cliquez sur Connecter le compte
3. Connectez-vous à Instagram et autorisez
4. Confirmez que le compte Instagram Business est lié

Note : Les comptes Instagram personnels ne peuvent pas utiliser l'API Graph. Convertissez-le en compte Business ou Creator dans les paramètres Instagram.

Étape 3 : Obtenir les jetons d'accès

Générer un jeton d'accès utilisateur :

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

Autorisations requises

Étape 4 : Échanger le jeton contre un jeton de longue durée

Les jetons de courte durée expirent en 1 heure. Échangez-les contre un jeton de longue durée (60 jours) :

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

// Utilisation
const longLivedToken = await exchangeForLongLivedToken(shortLivedToken);
console.log(`Le jeton expire : ${new Date(longLivedToken.expires_at * 1000)}`);

Étape 5 : Obtenir l'ID du compte Instagram Business

Récupérer le compte Instagram connecté :

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

// Utilisation
const igAccountId = await getInstagramAccountId('12345678', accessToken);
console.log(`ID du compte Instagram : ${igAccountId}`);

Étape 6 : Effectuer des appels API authentifiés

Créer un client API réutilisable :

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

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

Publication de contenu

Publication d'une photo

Publier une photo sur Instagram :

const publishPhoto = async (igAccountId, photoData) => {
  // Étape 1 : Créer un conteneur média
  const containerResponse = await instagramRequest(`/${igAccountId}/media`, {
    method: 'POST',
    image_url: photoData.imageUrl,
    caption: photoData.caption,
    location_id: photoData.locationId, // Facultatif
    is_carousel_item: 'false'
  });

  const creationId = containerResponse.id;

  // Étape 2 : Publier le média
  const publishResponse = await instagramRequest(`/${igAccountId}/media_publish`, {
    method: 'POST',
    creation_id: creationId
  });

  return publishResponse;
};

// Utilisation
const post = await publishPhoto({
  igAccountId: '17841400000000000',
  imageUrl: 'https://example.com/image.jpg',
  caption: 'Nous sommes ravis d\'annoncer notre nouveau produit ! 🚀 #lancement #innovation',
  locationId: '123456789' // Facultatif
});

console.log(`ID du média publié : ${post.id}`);

Publication d'une vidéo

Publier une vidéo sur Instagram :

const publishVideo = async (igAccountId, videoData) => {
  // Étape 1 : Créer un conteneur média
  const containerResponse = await instagramRequest(`/${igAccountId}/media`, {
    method: 'POST',
    video_url: videoData.videoUrl,
    cover_url: videoData.coverUrl, // Miniature facultative
    caption: videoData.caption,
    media_type: 'REELS', // ou 'VIDEO' pour le fil d'actualité
    share_to_feed: 'true' // Pour les Reels
  });

  const creationId = containerResponse.id;

  // Attendre le traitement de la vidéo (interroger jusqu'à ce que le statut soit EXPIRED ou FINISHED)
  await waitForVideoProcessing(creationId);

  // Étape 2 : Publier le média
  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('Le traitement de la vidéo a expiré');
    }

    await new Promise(resolve => setTimeout(resolve, 2000));
  }

  throw new Error('Délai de traitement de la vidéo dépassé');
};

Publication d'un carrousel (Plusieurs images/vidéos)

Publier plusieurs éléments multimédias dans une seule publication :

const publishCarousel = async (igAccountId, carouselData) => {
  const children = [];

  // Étape 1 : Créer chaque élément du carrousel
  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);
  }

  // Étape 2 : Créer un conteneur de carrousel avec des enfants
  const carouselContainerResponse = await instagramRequest(`/${igAccountId}/media`, {
    method: 'POST',
    media_type: 'CAROUSEL',
    children: children.join(','),
    caption: carouselData.caption
  });

  const creationId = carouselContainerResponse.id;

  // Étape 3 : Publier le carrousel
  const publishResponse = await instagramRequest(`/${igAccountId}/media_publish`, {
    method: 'POST',
    creation_id: creationId
  });

  return publishResponse;
};

// Utilisation
const carousel = await publishCarousel('17841400000000000', {
  caption: 'Présentation des produits 2026',
  items: [
    { type: 'image', url: 'https://example.com/img1.jpg', caption: 'Produit 1' },
    { type: 'image', url: 'https://example.com/img2.jpg', caption: 'Produit 2' },
    { type: 'video', url: 'https://example.com/vid1.mp4', caption: 'Démo' }
  ]
});

Types de médias

Récupération des médias et des statistiques

Obtention des médias de l'utilisateur

Récupérer les médias publiés :

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

// Utilisation
const media = await getUserMedia('17841400000000000');
media.data.forEach(item => {
  console.log(`${item.media_type}: ${item.caption}`);
  console.log(`J'aime : ${item.like_count}, Commentaires : ${item.comments_count}`);
  console.log(`URL : ${item.permalink}`);
});

Obtention des statistiques des médias

Récupérer les analyses pour un média spécifique :

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

  return response;
};

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

Métriques de statistiques disponibles

Obtention des statistiques du compte

Récupérer les analyses agrégées du compte :

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

// Utilisation - Obtenir les métriques des 30 derniers jours
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}`);
  });
});

Métriques au niveau du compte

Gestion des commentaires

Obtention des commentaires

Récupérer les commentaires sur les médias :

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

  return response;
};

// Utilisation
const comments = await getMediaComments('17890000000000000');
comments.data.forEach(comment => {
  console.log(`@${comment.username}: ${comment.text}`);
  console.log(`Masqué : ${comment.hidden}`);
});

Répondre aux commentaires

Publier une réponse à un commentaire :

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

  return response;
};

// Utilisation
const reply = await replyToComment(
  '17890000000000000',
  '17900000000000000',
  'Merci de votre intérêt ! Vérifiez vos MP pour plus de détails.'
);
console.log(`Réponse publiée : ${reply.id}`);

Masquer les commentaires

Masquer les commentaires inappropriés :

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

  return response;
};

// Utilisation
await hideComment('17900000000000000');
console.log('Commentaire masqué');

Suppression des commentaires

Supprimer les commentaires indésirables ou inappropriés :

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

  console.log('Commentaire supprimé');
};

Webhooks

Configuration des webhooks

Configurez des webhooks pour les notifications en temps réel :

const subscribeToWebhooks = async (appId, pageId, accessToken) => {
  // S'abonner aux événements 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();
};

Gestion des 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 vérifié');
    res.status(200).send(challenge);
  } else {
    res.status(403).send('Vérification échouée');
  }
});

// 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('Non trouvé');
  }

  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(`Nouveau commentaire sur le média ${data.media_id}`);
  console.log(`De : ${data.from_id}`);
  console.log(`Texte : ${data.text}`);

  // Réponse automatique ou modération
  if (isSpam(data.text)) {
    await hideComment(data.id);
  }
}

Champs de webhook

Limitation du débit

Comprendre les limites de débit

L'API Graph d'Instagram impose :

• 200 appels par heure par application (partagés entre tous les utilisateurs)
• Découverte d'entreprise : 200 appels par heure par utilisateur
• Publication de contenu : Limitée par type d'action

Dépasser les limites entraîne un code d'erreur HTTP 400 avec le sous-code 613.

Bonnes pratiques de limitation du débit

1. Mettre en cache les réponses - Ne pas récupérer les données inchangées
2. Regrouper les requêtes - Utiliser l'expansion de champ pour réduire les appels
3. Utiliser les webhooks - Mises à jour en temps réel au lieu du polling
4. Implémenter un backoff - Backoff exponentiel sur les erreurs 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(`Limite de débit atteinte. Nouvelle tentative dans ${delay}ms...`);
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw error;
      }
    }
  }
};

Dépannage des problèmes courants

Problème : Jeton OAuth expiré

Symptômes : Obtention d'erreurs « Jeton d'accès OAuth invalide ».

Solutions :

1. Mettre en œuvre le rafraîchissement du jeton avant l'expiration de 60 jours
2. Stocker la date d'expiration du jeton et alerter avant l'expiration
3. Réauthentifier l'utilisateur si le jeton a expiré

Problème : Échec de la publication du média

Symptômes : La publication renvoie une erreur.

Solutions :

1. Vérifier que l'URL de l'image est accessible publiquement (aucune authentification requise)
2. Vérifier le format de l'image (JPEG, PNG) et la taille (<8 Mo)
3. S'assurer que la vidéo est au format MP4, <1 Go, <90 secondes
4. Attendre le traitement de la vidéo avant de publier

Problème : Statistiques non disponibles

Symptômes : L'API Insights renvoie des données vides.

Solutions :

1. Vérifier que le compte est Business ou Creator (pas Personnel)
2. Attendre 24 à 48 heures pour que les statistiques se remplissent
3. Vérifier que le compte a une activité suffisante

Liste de vérification pour le déploiement en production

Avant de passer en production :

• [ ] Convertir tous les comptes de test en Business/Creator
• [ ] Implémenter OAuth 2.0 avec des jetons de longue durée
• [ ] Stocker les jetons en toute sécurité avec chiffrement
• [ ] Implémenter le rafraîchissement automatique des jetons
• [ ] Configurer les points de terminaison des webhooks avec HTTPS
• [ ] Ajouter la limitation du débit et la mise en file d'attente des requêtes
• [ ] Implémenter une gestion complète des erreurs
• [ ] Ajouter la journalisation pour tous les appels API
• [ ] Créer des flux de travail de modération de contenu
• [ ] Tester avec plusieurs types de comptes

Cas d'utilisation réels

Outil de planification de médias sociaux

Une plateforme marketing automatise la publication :

• Défi : Publication manuelle sur plus de 50 comptes clients
• Solution : Publication programmée via l'API Instagram
• Résultat : 80 % de gain de temps, calendrier de publication cohérent

Implémentation clé :

• Calendrier de contenu avec planification par glisser-déposer
• Publication automatique de photos, vidéos, carrousels
• Suggestions de hashtags basées sur le contenu

Automatisation du service client

Une marque e-commerce automatise les réponses aux commentaires :

• Défi : Réponse lente aux demandes des clients
• Solution : Réponse automatique aux questions courantes via webhook
• Résultat : Temps de réponse moyen de 5 minutes, 90 % de satisfaction

Implémentation clé :

• Détection de mots-clés (prix, disponibilité, livraison)
• Réponse automatique avec des liens vers les produits
• Transférer les requêtes complexes aux agents humains

Conclusion

L'API Graph d'Instagram offre un accès complet aux fonctionnalités des comptes Instagram Business et Creator. Points clés à retenir :

• Authentification Facebook Login OAuth 2.0 avec des jetons de 60 jours
• La publication de contenu prend en charge les photos, vidéos, Reels et carrousels
• L'API Insights fournit des données sur l'engagement, la portée et la démographie
• Les webhooks permettent la surveillance en temps réel des commentaires et des mentions
• La limite de débit de 200 appels/heure par application nécessite une gestion prudente
• Apidog simplifie les tests d'API et la collaboration en équipe

Section FAQ

Comment obtenir l'accès à l'API Instagram ?

Créez un compte développeur Facebook, créez une application Business, ajoutez le produit Instagram Graph API et authentifiez-vous via Facebook Login avec les autorisations requises.

Puis-je publier sur Instagram automatiquement ?

Oui, utilisez l'API de publication de contenu pour publier des photos, des vidéos, des Reels et des carrousels sur les comptes Business et Creator.

Quels types de comptes Instagram prennent en charge l'API ?

Seuls les comptes Business et Creator disposent d'un accès API complet. Les comptes personnels ont un accès API limité ou inexistant.

Comment obtenir les commentaires d'Instagram ?

Utilisez le point de terminaison des commentaires (/{media-id}/comments) pour récupérer les commentaires sur un média spécifique. Les webhooks fournissent des notifications en temps réel.

Quelles sont les limites de débit d'Instagram ?

L'API Graph d'Instagram autorise 200 appels par heure par application. Certains points de terminaison ont des limites supplémentaires par utilisateur.

Puis-je publier des Stories via l'API ?

Oui, les Stories peuvent être publiées en utilisant le même flux de publication de contenu que les publications du fil d'actualité.

Comment accéder aux statistiques Instagram ?

Demandez la permission instagram_manage_insights pendant l'OAuth. Utilisez le point de terminaison Insights pour récupérer les métriques pour les médias et le compte.

Puis-je répondre automatiquement aux commentaires ?

Oui, utilisez l'API de commentaires pour publier des réponses. De nombreuses marques l'utilisent pour les réponses automatisées du service client.