oEmbed Instagram

Vous pouvez interroger le point de terminaison oEmbed Instagram de manière à obtenir le code d’intégration HTML et les métadonnées de base d’une publication Instagram, pour afficher celle-ci dans un autre site web ou une autre application. Prend en charge la publication de photos, de vidéos, de reels et de guides.

Utilisations courantes

Affichage de publications dans des applications de messagerie
Intégration de publications dans des sites web ou des blogs
Affichage de publications dans des systèmes de gestion de contenu

Points de terminaison

Point de terminaison	Description
`GET /instagram_oembed`	Récupérez le code d’intégration HTML et les métadonnées de base d’une publication Instagram.

Conditions requises

Un compte de développeur Facebook
Une application Facebook en mode Live
Un token d’accès
Contrôle app pour la fonctionnalité oEmbed Read

Limites

Le point de terminaison oEmbed Instagram est destiné uniquement à permettre l’intégration de contenus Instagram dans des sites web et des applications. Veuillez ne pas l’utiliser à d’autres fins. Il est strictement interdit d’utiliser des métadonnées, une page, une publication ou un contenu vidéo (ou des dérivés de ceux-ci) provenant d’un point de terminaison à d’autres fins que la fourniture d’une vue frontale de la Page, de la publication ou de la vidéo concernée. Cette interdiction s’applique à la consommation, à la manipulation, à l’extraction ou à la persistance des métadonnées et du contenu, y compris, mais sans s’y limiter, au fait de déduire des informations sur les pages, les publications et les vidéos à partir des métadonnées à des fins d’analyse.
Les publications des comptes Instagram privés, inactifs et associés à des restrictions d’âge ne sont pas prises en charge.
Les comptes dont leséléments intégrés sont désactivés ne sont pas pris en charge.
Les stories ne sont pas prises en charge.
Shadow DOM n’est pas pris en charge.

Contrôle app

Pour pouvoir utiliser oEmbed, vous devez soumettre votre application au Contrôle app pour la fonctionnalité oEmbed Read.

Pour le champ de formulaire fournir l’URL à laquelle nous pouvons tester oEmbed Read, utilisez le point de terminaison oEmbed Instagram pour obtenir le code d’intégration HTML de toute publication publique sur notre Page Facebook ou Page Instagram officielle (ou obtenez ce code d’intégration HTML directement sur ces pages). Intégrez le code d’intégration HTML renvoyé dans votre propre Page sur laquelle vous voulez afficher le contenu oEmbed et saisissez l’URL de cette page dans le champ de formulaire.

Une fois approuvé pour la fonctionnalité oEmbed Read, vous pourrez intégrer vos propres pages, publications ou vidéos avec leurs URL respectives.

Tokens d’accès

Le point de terminaison oEmbed Instagram requiert soit un token d’accès d’application (recommandé), soit un token d’accès client.

Tokens d’accès d’application

Si votre application repose sur un serveur backend, nous vous recommandons d’utiliser un token d’accès d’application pour accéder au point de terminaison oEmbed. Les limites de débit dépendent du type de token inclus dans la demande, et la limite de débit des tokens d’application s’élève à cinq millions de demandes quotidiennes.

Vous trouverez des instructions pour générer des tokens d’accès d’app dans la section Tokens d’app de notre documentation sur les tokens d’accès.

Notez que les tokens d’accès d’app ne doivent jamais être utilisés côté client. Ils doivent toujours rester en sécurité sur votre serveur. Si votre application a besoin d’un token d’accès côté client, utilisez plutôt un token d’accès client.

Tokens d’accès client·e

Si votre application requiert un accès au point de terminaison oEmbed à partir d’un agent utilisateur tel qu’un appareil mobile ou un navigateur web, elle doit utiliser un token d’accès client et est alors soumise aux limites de débit des tokens client.

Pour obtenir un token d’accès client, connectez-vous à l’Espace App et accédez à Paramètres > Avancés > Sécurité > Token client.

Contrairement aux tokens d’accès d’application, les tokens d’accès client ne peuvent pas être utilisés seuls dans les demandes envoyées au point de terminaison oEmbed. Ils doivent être associés à votre ID d’app. Pour ce faire, ajoutez votre token à la fin de votre ID d’app, en le séparant de celui-ci avec une barre verticale (|), comme suit :

{app-id}|{client-token}

Par exemple :

access_token=1234|5678

Plafonds

Les limites de débit dépendent du type de token d’accès que votre application inclut dans chaque demande.

Limites de débit des tokens d’application

Les applications qui utilisent des tokens d’accès d’application peuvent effectuer jusqu’à cinq millions de demandes toutes les 24 heures.

Limites de débit des tokens client

Les limites de débit des tokens client sont significativement plus basses que celles des tokens d’application. Nous ne révélons pas les limites réelles, car elles varient en fonction de l’activité de votre application. Cependant, vous pouvez partir du principe que votre application n’atteindra pas sa limite, à moins qu’elle se comporte comme un bot, par exemple en générant des lots comprenant des milliers de demandes ou en envoyant des milliers de demandes par agent ou utilisateur de l’application.

Récupération du code d’intégration HTML

Pour obtenir le code d’intégration HTML d’une publication Instagram, envoyez une demande de type :

GET /instagram_oembed?url={url}&access_token={access-token}

Remplacez {url} par l’URL de la publication Instagram que vous souhaitez demander et {access-token} par votre token d’accès d’application ou client (ou envoyez-le-nous dans un en-tête HTTP). Si vous utilisez un Token d’accès client, gardez à l’esprit que vous devez l’associer à votre ID d’app avec une barre verticale, sans quoi la demande échouera.

En cas de réussite, l’API renvoie un objet JSON contenant le code d’intégration HTML de la publication, ainsi que d’autres données. Le code d’intégration HTML sera attribué à la propriété html.

Reportez-vous à la documentation de référence oEmbed Instagram pour connaître la liste des paramètres de chaîne de requête que vous pouvez inclure pour préciser la demande. Vous pouvez également inclure le paramètre de chaîne de requête fields afin de spécifier les champs que vous souhaitez obtenir. Si vous omettez ce paramètre, tous les champs par défaut seront inclus dans la réponse.

Exemple de requête

curl -X GET \
  "https://graph.facebook.com/v19.0/instagram_oembed?url=https://www.instagram.com/p/fA9uwTtkSN/&access_token=IGQVJ..."

Exemple de réponse

Certaines valeurs sont tronquées à l’aide de points de suspension (...) pour plus de lisibilité.

{
  "version": "1.0",
  "author_name": "diegoquinteiro",
  "provider_name": "Instagram",
  "provider_url": "https://www.instagram.com/",
  "type": "rich",
  "width": 658,
  "html": "<blockquote class=\"instagram-media\" data-instgrm-ca...",
  "thumbnail_width": 640,
  "thumbnail_height": 640
}

Formats d’URL

Le paramètre de chaîne de requête url accepte les formats d’URL suivants :

https://www.instagram.com/p/{media-shortcode}/
https://www.instagram.com/tv/{media-shortcode}/https://www.instagram.com/{username}/guide/{slug}/{guide_id}

Code d’intégration JS

Le code HTML d’intégration contient une référence à la bibliothèque JavaScript Instagram embed.js. Lorsque la bibliothèque se charge, elle recherche sur la page le code HTML de la publication et génère une vue complète de celle-ci. Si vous souhaitez charger la bibliothèque séparément, incluez le paramètre de chaîne de requête omitscript=true dans votre demande. Pour initialiser manuellement le code d’intégration HTML, appelez la fonction instgrm.Embeds.process() après le chargement de la bibliothèque.

Taille de la publication

La publication intégrée est dynamique et s’adapte à la taille de son conteneur. Par conséquent, sa hauteur varie selon la largeur du conteneur et la longueur de la légende. Vous pouvez définir une largeur maximale en incluant le paramètre de chaîne de requête maxwidth dans votre demande.

Récupération de miniatures

Nous vous recommandons d’afficher le code d’intégration HTML de la publication dans son intégralité lorsque cela est possible. Sinon, vous pouvez utiliser l’URL de l’image miniature d’une publication et afficher cette miniature à la place de la publication. Dans ce cas, cependant, vous devez fournir une attribution claire à côté de l’image, y compris en l’attribuant à l’auteur original et à Instagram, ainsi qu’un lien vers la publication Instagram qui fait l’objet de votre requête.

Pour obtenir l’URL de la miniature d’une publication et ses informations d’attribution, envoyez une demande à :

GET /instagram_oembed
  ?url={url}
  &maxwidth={maxwidth}
  &fields=thumbnail_url,author_name,provider_name,provider_url
  &access_token={access-token}

Remplacez {url} par l’URL de la publication Instagram que vous souhaitez interroger, {maxwidth} par la taille maximale de la miniature que vous souhaitez afficher et {access-token} par votre token d’accès d’application ou client.

Exemple de requête

curl -i -X GET \
  "https://graph.facebook.com/v19.0/instagram_oembed?url=https%3A%2F%2Fwww.instagram.com%2Fp%2FfA9uwTtkSN&maxwidth=320&fields=thumbnail_url%2Cauthor_name%2Cprovider_name%2Cprovider_url&access_token=96481..."

Exemple de réponse

Certaines valeurs sont tronquées à l’aide de points de suspension (...) pour plus de lisibilité.

{
  "thumbnail_url": "https://scontent.cdninstagram.com/v/t51.288...",
  "author_name": "diegoquinteiro",
  "provider_name": "Instagram",
  "provider_url": "https://www.instagram.com/"
}

Passage des tokens d’accès dans un en-tête

Si vous ne souhaitez pas inclure le token d’accès dans la chaîne de requête de votre demande, vous pouvez nous le transmettre via un en-tête HTTP Authorization.

Authorization: Bearer {access-token}

Par exemple :

curl -i -X GET \
  "https://graph.facebook.com/v19.0/instagram_oembed?url=https%3A%2F%2Fwww.instagram.com%2Fp%2FfA9uwTtkSN" \
  --header "Authorization: Bearer 96481..."