La réponse en une phrase
graph.facebook.com/v21.0), le même système d'authentification et la même configuration d'App. « Instagram Messaging API » est le label marketing utilisé par Meta pour désigner les capacités spécifiques aux DM au sein de la Graph API plus large.La confusion vient du fait que Meta commercialise différentes capacités d'API sous différents noms de produits — « Instagram Graph API » pour la plateforme complète, « Instagram Messaging API » ou « Messenger API for Instagram » pour le sous-ensemble spécifique aux DM. Les développeurs cherchant « Instagram Messaging API » tombent souvent sur une documentation qui se lit comme s'il s'agissait d'un système complètement différent. Ce n'est pas le cas. Vous configurez une seule App Facebook, vous obtenez un seul jeu de tokens, et vous utilisez différents endpoints et permissions selon ce que vous construisez.
Qu'est-ce que la Instagram Graph API ?
La Instagram Graph API est l'API officielle et complète destinée aux comptes Instagram Business et Creator. C'est la seule manière légitime d'accéder de façon programmatique aux données et fonctionnalités d'Instagram — de la publication de contenu à la lecture des analytics en passant par la réponse aux DM, tout passe par elle.
La Graph API couvre six grands domaines de capacités :
- Gestion de contenu — créer, publier et récupérer des posts, reels, stories et carrousels au nom d'un compte business
- Insights médias — lire les impressions, la portée, l'engagement et les données d'audience pour les médias individuels et les métriques au niveau du compte
- Commentaires — lire les commentaires sur les posts, y répondre, les supprimer, les masquer
- Recherche par hashtag — rechercher des posts publics par hashtag (avec des rate limits significatifs)
- Mentions — détecter quand d'autres comptes mentionnent ou taguent votre compte business dans des posts ou stories
- Direct Messages — recevoir et envoyer des DM, gérer les réponses aux stories et les mentions de stories (c'est le sous-ensemble « Messaging API »)
Ces six domaines font tous partie de la même Graph API. La base URL, le système d'authentification, le processus d'App Review et le type de token sont identiques pour tous. Les différences résident dans les endpoints que vous appelez, les permissions que vous demandez et les champs webhook auxquels vous vous abonnez.
Que désigne précisément l'« Instagram Messaging API » ?
Quand Meta (et la plupart des documentations tierces) parle d'« Instagram Messaging API » ou de « Messenger API for Instagram », il s'agit du sous-ensemble de la Graph API qui permet :
- De recevoir des DM — événements webhook lorsque des utilisateurs envoient un direct message à votre compte business
- D'envoyer des DM — appeler
POST /{ig-user-id}/messagespour envoyer une réponse à l'IGSID d'un utilisateur - Les réponses aux stories — événements webhook lorsque des utilisateurs répondent à votre story via DM (arrivent avec
message.reply_to.story) - Les mentions de stories — événements webhook lorsque des utilisateurs taguent votre compte dans leur story (arrivent sous forme d'événement de référence)
- Les réactions emoji — événements webhook lorsque des utilisateurs réagissent à l'un de vos messages
- Les accusés de lecture — événements webhook lorsque des utilisateurs lisent vos messages
C'est un sous-ensemble ciblé, exclusivement DM, de ce que la Graph API complète peut faire. Il nécessite des permissions de messagerie spécifiques (instagram_manage_messages), des abonnements webhook spécifiques (messages, messaging_referrals) et son propre endpoint d'envoi. Mais il fonctionne sur la même infrastructure, la même authentification et la même App que tout le reste.
Cartographie complète des endpoints : Graph API vs Messaging API
Voici une cartographie complète des endpoints de la Instagram Graph API, étiquetés selon qu'ils relèvent uniquement de la Graph API, uniquement de la Messaging API (le sous-ensemble « Messaging API »), ou des deux :
Permissions : ce dont vous avez besoin pour chaque capacité
Les permissions sont la façon la plus claire de distinguer ce qu'exige la « Messaging API » par rapport à ce dont le reste de la Graph API a besoin. Chaque permission nécessite une App Review pour une utilisation en production au-delà des comptes de test.
| Permission | Catégorie | Ce qu'elle permet |
|---|---|---|
| instagram_manage_messages | Messaging API | Recevoir les événements webhook de DM. Envoyer des réponses DM via /{ig-user-id}/messages. Accéder à l'historique des conversations. Requis pour toute automatisation DM. |
| pages_messaging | Messaging API | S'abonner et recevoir les événements webhook via la Page Facebook liée. Sans cela, les webhooks DM Instagram ne se déclenchent pas, quelles que soient les autres permissions. |
| pages_read_engagement | Les deux | Lire les informations de base sur la Page Facebook liée et le compte Instagram. Requis à la fois pour les fonctionnalités de messagerie et celles de la Graph API pour la vérification du compte. |
| instagram_manage_insights | Graph API | Lire les données analytics au niveau du compte et des médias, y compris les impressions, la portée, l'engagement, la démographie des followers. Pour les dashboards analytics et les outils de reporting. |
| instagram_content_publish | Graph API | Créer et publier posts, reels, stories et carrousels au nom d'un compte business. Pour les outils de planification et de publication de contenu. |
| instagram_manage_comments | Graph API | Lire, répondre, masquer et supprimer les commentaires sur les posts. Pour les outils de gestion de commentaires et l'automatisation commentaire-vers-DM (nécessite aussi instagram_manage_messages pour l'étape d'envoi du DM). |
| instagram_basic | Graph API | Lire les informations de profil de base et la liste des posts. Souvent incluse comme permission de base aux côtés de permissions plus spécifiques pour la plupart des cas d'usage de la Graph API. |
Abonnements webhook : messagerie vs tout le reste
C'est dans les abonnements aux champs webhook que la Messaging API et le reste de la Graph API divergent le plus clairement. Tous les abonnements passent par les paramètres Instagram Webhooks de votre App Facebook, mais les champs auxquels vous vous abonnez déterminent les événements que vous recevez :
Le chevauchement le plus déroutant : les événements liés aux stories se répartissent sur deux champs webhook différents. Un utilisateur qui répond à votre story est un événement de messagerie (champ messages). Un utilisateur qui tague votre compte dans sa propre story est un événement de référence (champ messaging_referrals). Un compte qui vous mentionne dans une légende est un événement non-messagerie (champ mentions). Trois champs webhook différents pour trois interactions superficiellement similaires.
L'ancienne Instagram API dépréciée — ce qu'elle était et pourquoi cela compte
La question Stack Overflow de 2019 qui remonte souvent pour cette requête comparait deux choses qui n'existent plus sous la même forme aujourd'hui : l'« Instagram API » (entièrement dépréciée désormais) et l'« Instagram Graph API » (actuelle). Comprendre cette histoire explique pourquoi tant de réponses en ligne sont erronées.
Matrice de décision : que choisir pour votre cas d'usage
instagram_manage_messages, pages_messaging. Champs webhook : messages, messaging_referrals.instagram_manage_insights, instagram_basic.instagram_content_publish, instagram_basic.instagram_manage_comments.instagram_manage_comments + instagram_manage_messages.Questions fréquentes
graph.facebook.com/v21.0), le même système d'authentification et la même configuration d'App Facebook. « Instagram Messaging API » est le nom de produit utilisé par Meta pour désigner les capacités spécifiques aux DM au sein du cadre plus large de la Graph API.instagram_manage_messages + pages_messaging + pages_read_engagement. Analytics (Graph API) : instagram_manage_insights + instagram_basic. Publication de contenu (Graph API) : instagram_content_publish + instagram_basic. Commentaires (Graph API) : instagram_manage_comments. Toutes nécessitent une App Review pour une utilisation en production.api.instagram.com. Elle permettait l'accès aux comptes personnels et utilisait un OAuth spécifique à Instagram. Elle a été entièrement arrêtée en mars 2020 et ne fonctionne plus. Toutes les intégrations Instagram actuelles doivent utiliser l'Instagram Graph API (graph.facebook.com). Tout tutoriel faisant référence à « api.instagram.com » décrit un système cassé et déprécié.messages. Pour les mentions de stories (quand des utilisateurs taguent votre compte dans leur story) : champ messaging_referrals. Pour les @mentions dans les légendes/commentaires de posts : champ mentions (non-messagerie, Graph API). Pour les commentaires sur les posts : champ comments (Graph API). Abonnez-vous à tous les champs dont vous avez besoin dans les paramètres Instagram Webhooks de votre App Facebook.POST /v21.0/{ig-user-id}/messages appelé sur graph.facebook.com. Le ig-user-id est l'ID numérique de votre Instagram Business Account (également la valeur entry[0].id dans les webhooks entrants). Le corps de la requête : {"recipient": {"id": "USER_IGSID"}, "message": {"text": "your reply"}}. Authentifié avec un Page Access Token disposant de la permission instagram_manage_messages.La couche webhook de la Messaging API,
prise en charge pour vous.
Maintenant que vous savez que la Messaging API est un sous-ensemble de la Graph API, l'étape suivante consiste à recevoir ces événements sur votre serveur. SocialHook gère la vérification HMAC, le parsing du payload brut et la normalisation des événements — chaque DM, réponse à une story et mention de story arrive sous forme de JSON propre à votre endpoint.