Se connecterCommencer l’essai gratuit
easyCoexistence API officielles

Pièces jointes des DM Instagram dans le webhook des messages

Le webhook messages d'Instagram transporte les médias des DM dans message.attachments : un tableau d'objets, chacun avec un type et un payload qui contient en général une URL CDN. La liste de Meta pour Instagram Login comprend image, video, audio, file, ig_post, ig_reel, reel, story_mention, media, story, ig_story et l'ancien share, et les médias à vue unique arrivent sous forme de pièce jointe ephemeral sans URL.

easyCoexistence abonne chaque compte Instagram connecté aux messages et transmet les DM avec leurs pièces jointes à votre endpoint HTTPS tel que Meta les envoie, signés avec le secret de ce compte et sans copie conservée, afin que votre agent ou votre code récupère les médias dont il a besoin.

ig_post

Type de pièce jointe pour un post partagé ; son payload ajoute ig_post_media_id et title, la légende du post, à côté de url.

1 Feb 2026

Date à laquelle l'ancien type de pièce jointe share a cessé d'être pris en charge pour les partages de posts Instagram.

ephemeral

Type de pièce jointe pour les médias éphémères à vue unique, qui arrivent sans URL.

is_unsupported

Passé à true sur un événement message lorsque le message contient un média non pris en charge.

First image

Ce qu'une notification signale quand quelqu'un réagit à une seule image d'un post en carrousel, ou la transfère.

Quels types de pièces jointes un événement DM peut-il contenir ?

Les exemples d'Instagram Login de Meta listent ces valeurs pour message.attachments[].type, chacune avec un objet payload. La plupart des payloads contiennent une url vers le média sur le CDN de Meta, et Meta ne documente des champs supplémentaires dans le payload que pour ig_post. Lisez donc le type avant le payload.

imageA photo. Meta's Instagram Login list also puts GIFs and stickers under this type.
videoA video, at payload.url.
audioAudio, at payload.url.
fileA file, at payload.url.
ig_postA shared post: url, ig_post_media_id and title, its caption.
ig_reel and reelA shared Reel; Meta lists both names, each with a url.
story_mentionA Story that mentions the account, at its CDN URL.
shareThe legacy post share, supported until 1 February 2026.
media, story, ig_storyAlso in Meta's list, with no payload described.
ephemeralView-once media, sent with no URL.

À quoi ressemble un DM avec pièces jointes ?

Un événement messages dont l'objet message contient des attachments à la place du texte, ou en plus de celui-ci. L'exemple de Meta envoie deux médias dans un même message, chacun avec son propre type et son payload.url ; un gestionnaire doit donc parcourir le tableau plutôt que lire seulement son premier élément :

A DM with two attachments, as Meta sends it
{
  "object": "instagram",
  "entry": [
    {
      "id": "<IG_ID>",
      "time": 1793448000512,
      "messaging": [
        {
          "sender": { "id": "<IGSID>" },
          "recipient": { "id": "<IG_ID>" },
          "timestamp": 1793447999874,
          "message": {
            "mid": "<MESSAGE_ID>",
            "attachments": [
              { "type": "image", "payload": { "url": "<CDN_URL>" } },
              { "type": "video", "payload": { "url": "<CDN_URL>" } }
            ]
          }
        }
      ]
    }
  ]
}

À quoi ressemble un post partagé ?

Une pièce jointe ig_post. Depuis le 3 novembre 2025, Meta envoie les partages de posts avec à la fois une pièce jointe share et une pièce jointe ig_post ; share était pris en charge pour les posts jusqu'au 1er février 2026, et Meta indique que les nouvelles intégrations doivent prendre en charge ig_post. Son payload ajoute l'identifiant média du post et sa légende, dans title :

The attachment of a shared post
"attachments": [
  {
    "type": "ig_post",
    "payload": {
      "ig_post_media_id": "<MEDIA_ID>",
      "title": "<POST_CAPTION>",
      "url": "<CDN_URL>"
    }
  }
]

Que signifie chaque champ ?

Les champs de pièce jointe que Meta documente pour un événement DM, du tableau vers le bas :

  • message.attachments[] : un objet par média ; l'exemple de Meta en contient deux dans un même message.
  • type : ce qu'est l'élément, selon la liste ci-dessus. Branchez-vous dessus avant de lire le payload.
  • payload.url : une URL CDN du média. La présentation générale de Meta qualifie ces URL de conçues pour protéger la vie privée : elles ne renvoient plus rien une fois le contenu supprimé ou expiré.
  • payload.ig_post_media_id et payload.title : uniquement pour ig_post, l'identifiant média du post partagé et sa légende.
  • message.text : présent uniquement quand le message contient aussi du texte.
  • message.is_unsupported : true quand le message contient un média que le webhook ne prend pas en charge.

Combien de temps les URL des pièces jointes restent-elles valides ?

Meta les lie au contenu. Sa présentation générale indique que les URL du CDN d'Instagram sont conçues pour protéger la vie privée et cessent de renvoyer le média une fois le contenu supprimé ou expiré, et son guide des mentions en Story précise que l'URL d'une Story cesse de s'afficher lorsque la Story expire ou est supprimée. Une application qui a besoin d'un fichier doit le récupérer à l'arrivée de l'événement, dans le respect des règles de Meta : les médias de Story, notamment, ne doivent pas être stockés ni mis en cache.

Quels médias le webhook laisse-t-il de côté ?

Le guide de messagerie Instagram de Meta cite ces lacunes, qu'un gestionnaire doit attendre plutôt que traiter comme des erreurs :

  • Médias éphémères, à vue unique ou rejouables : une pièce jointe de type ephemeral, sans URL.
  • Médias non pris en charge : le message arrive avec is_unsupported à true.
  • GIF et stickers : ce guide indique qu'ils ne déclenchent aucun webhook, alors que les exemples d'Instagram Login de Meta les classent sous image.
  • L'image choisie dans un carrousel : une réaction à une image d'un post en carrousel, ou son transfert, signale la première image.
  • Partages en général : les guides de messagerie de Meta indiquent encore que seule l'URL du média partagé est incluse, bien que ig_post ajoute désormais l'identifiant média et la légende.

Comment easyCoexistence transmet-il les pièces jointes ?

Inchangé, à l'intérieur de entry : un DM avec média arrive à votre endpoint avec le tableau attachments de Meta tel que Meta l'a envoyé, dans une enveloppe composée de platform, account_id, external_id et entry, signée avec X-EC-Signature. Les attachments ne sont pas téléchargés, et les événements ne sont pas stockés par défaut : un compte dont une automatisation est activée conserve le texte d'un DM, pas son média, pendant 7 jours. Récupérez le média dont vous avez besoin depuis payload.url à l'arrivée de l'événement, et ne stockez pas les médias de Story.

Erreurs courantes

  • Ne lire que la première pièce jointe. message.attachments est un tableau, et l'exemple de Meta contient deux éléments dans un même message : parcourez-le en entier.
  • Continuer à chercher le type share pour les posts partagés. Meta l'a pris en charge pour les posts jusqu'au 1er février 2026 ; lisez ig_post, avec l'identifiant média et la légende dans son payload.
  • Enregistrer payload.url pour le récupérer plus tard. L'URL cesse de renvoyer le média une fois le contenu supprimé ou expiré : téléchargez ce dont vous avez besoin à l'arrivée, sauf les médias de Story.
  • Lire payload.url sans vérifier le type. Les médias à vue unique arrivent en ephemeral sans URL, et les médias non pris en charge mettent is_unsupported à true.
Faire cela avec EasyCoexistence

send_social_dm répond dans la fenêtre de 24 heures. De US$ 9 à US$ 0,75 par connexion et par mois, dégressif à mesure que vous ajoutez des connexions, avec un essai gratuit de 3 jours.

Questions fréquemment posées

Puis-je stocker les médias d'une pièce jointe de DM Instagram ?

Téléchargez ce dont vous avez besoin à l'arrivée de l'événement, car payload.url cesse de renvoyer le média une fois le contenu supprimé ou expiré. Les médias de Story font exception : les règles de Meta interdisent de les stocker ou de les mettre en cache.

Pourquoi un webhook DM Instagram n'a-t-il pas d'URL de média ?

En général parce que le média est à vue unique, ce qui arrive en pièce jointe ephemeral sans URL, ou qu'il n'est pas pris en charge, ce qui met is_unsupported à true.

Les GIF et stickers Instagram déclenchent-ils le webhook messages ?

La documentation de Meta se contredit : ses exemples Instagram Login classent les GIF et stickers sous image, tandis que son guide de messagerie Instagram indique qu'ils ne déclenchent aucun webhook. Testez avec un compte réel.

Un même événement DM Instagram peut-il contenir plusieurs pièces jointes ?

Oui. message.attachments est un tableau, et l'exemple de Meta montre deux médias dans un seul message.

Poursuivre la lecture

Connectez votre premier canal en deux minutes.

Aucune validation de plateforme à attendre. Connectez WhatsApp, Instagram, TikTok ou un autre canal, puis demandez à votre IA de publier, de répondre ou de faire un rapport, et regardez-la travailler.

  • 3 jours gratuits
  • Résiliable à tout moment
  • API officielles uniquement
  • Supervisé 24/7

Vérifié le