Webhook des messages Instagram : payload DM, échos et champs
Le champ messages du webhook Instagram transmet les DM d'un compte professionnel dès leur arrivée : texte, pièces jointes, partages, réponses aux Stories et mentions, réponses en ligne et suppressions. Chaque événement figure dans un tableau messaging avec l'ID Instagram-scoped de l'expéditeur, le destinataire, un horodatage et un objet message, et les messages envoyés par le compte lui-même reviennent sur le même champ avec is_echo défini à true.
easyCoexistence abonne chaque compte Instagram connecté aux messages et transmet ses DM, échos compris, à votre endpoint HTTPS dès leur arrivée, signés avec le secret de ce compte ; le transfert ne conserve aucune copie, et les DM ne sont pas stockés par défaut.
Défini à true sur un événement message pour un message envoyé par le compte lui-même.
Fenêtre de messagerie standard pour la plupart des actions de l'utilisateur, pendant laquelle l'application peut répondre à la personne.
Type de pièce jointe pour un post partagé ; l'ancien type share n'était pris en charge que jusqu'au 1er février 2026.
Type de pièce jointe de l'événement DM que Meta envoie lorsqu'une personne mentionne le compte dans sa Story.
Sous-code d'erreur, sous le code 200, lorsque le titulaire du compte a désactivé l'accès aux messages directs Instagram.
Quand le champ messages se déclenche-t-il ?
Lorsqu'une personne envoie un DM au compte professionnel, et lorsque le compte en envoie un. Les exemples et références de Meta listent ces cas, chacun étant un événement messaging avec un objet message :
- Texte, et médias en pièces jointes : images, vidéos, audios et fichiers.
- Un post ou un Reel partagé, sous forme de pièce jointe
ig_post,ig_reelou reel. - Une réponse à une Story du compte, avec
reply_to.story, et une Story qui mentionne le compte, sous forme de pièce jointestory_mention. - Une réponse en ligne à un message précédent, avec
reply_to.mid, et une réponse rapide, avecquick_reply.payload. - Un message supprimé par la personne (
is_deleted), un média non pris en charge (is_unsupported) et un message d'une personne ayant cliqué sur une publicité Click-to-Direct (referral). - Un message envoyé par le compte, qui revient avec
is_echodéfini à true.
À quoi ressemble une notification de messages ?
Un POST dont le JSON a object défini à instagram. Contrairement à un commentaire, un message se trouve dans un tableau messaging à l'intérieur de l'entrée du compte, et chaque élément contient sender, recipient, timestamp et message. Une réponse à une Story du compte ressemble à ceci :
{
"object": "instagram",
"entry": [
{
"id": "<IG_ID>",
"time": 1793448000512,
"messaging": [
{
"sender": { "id": "<IGSID>" },
"recipient": { "id": "<IG_ID>" },
"timestamp": 1793447999874,
"message": {
"mid": "<MESSAGE_ID>",
"text": "<MESSAGE_TEXT>",
"reply_to": {
"story": {
"url": "<CDN_URL_FOR_THE_STORY>",
"id": "<STORY_ID>"
}
}
}
}
]
}
]
}Que signifie chaque champ ?
Les champs que Meta documente pour un événement message sous Instagram Login, de l'extérieur vers l'intérieur :
- entry[].id : l'ID du compte professionnel. entry[].time : le moment où Meta a envoyé la notification ; les exemples de messagerie de Meta l'indiquent en millisecondes.
- sender.id et recipient.id : sur un DM entrant, l'ID Instagram-scoped de la personne et l'ID du compte ; sur un écho, les deux mêmes valeurs inversées.
- timestamp : le moment d'envoi du message, en millisecondes dans les exemples de Meta. Triez les messages selon ce champ, et non selon leur ordre d'arrivée.
- message.mid : l'ID du message, utile pour dédoublonner, réagir et répondre à ce message avec
reply_to.mid. - message.text : présent lorsque le message contient du texte.
- message.attachments[] : chacun avec un type et un payload, généralement une url. Le payload d'un post partagé
ig_postajouteig_post_media_idet title, sa légende. - message.
reply_to: mid pour une réponse en ligne, ou story avec l'url et l'id de la Story pour une réponse à une Story. - message.
quick_reply.payload et message.referral : la réponse rapide choisie, et le ref,ad_id, source, type etads_context_datade la publicité Click-to-Direct. - message.
is_deleted,is_echo,is_selfetis_unsupported: présents uniquement lorsqu'ils valent true. - message.
admin_textethandoff_reason: sur les applications éligibles, un avis indiquant qu'une application Meta, comme Meta Business Agent, a transmis la conversation ; il peut arriver sans mid ni texte.
Comment fonctionnent les échos ?
Lorsque le compte envoie un message, Meta envoie aussi un événement messages pour celui-ci, avec is_echo défini à true. sender.id désigne alors le compte et recipient.id l'ID Instagram-scoped de la personne ; un message de test que le compte s'envoie à lui-même porte aussi is_self. Les échos enregistrent ce que le compte a dit, ce dont un journal de conversation a besoin, mais un gestionnaire qui décide de répondre doit les ignorer. Meta n'envoie aucun écho lorsque le compte réagit à un message ou retire une réaction.
{
"object": "instagram",
"entry": [
{
"id": "<IG_ID>",
"time": 1793448061203,
"messaging": [
{
"sender": { "id": "<IG_ID>" },
"recipient": { "id": "<IGSID>" },
"timestamp": 1793448060950,
"message": {
"mid": "<MESSAGE_ID>",
"text": "<REPLY_TEXT>",
"is_echo": true
}
}
]
}
]
}Quel ID utiliser pour répondre ?
sender.id, l'ID Instagram-scoped de la personne. Meta le crée lorsqu'une personne écrit au compte ou commente ses médias, et il est propre à cette personne et à ce compte. POST /<IG_ID>/messages avec recipient.id défini à cette valeur envoie la réponse. L'événement ne contient ni nom ni nom d'utilisateur ; GET /<IGSID> avec les champs name et username les renvoie, car une personne qui a écrit au compte a donné le consentement que cette requête exige.
Comment un message ouvre-t-il la fenêtre de 24 heures ?
Une application ne peut écrire à une personne qu'après qu'elle a écrit au compte, et seulement dans la fenêtre de messagerie standard ouverte par son action. Pour la plupart des actions, elle dure 24 heures, et jusqu'à 7 jours après un premier message envoyé suite au clic sur une publicité Click-to-Direct. Un nouveau message de la personne ouvre une nouvelle fenêtre ; il faut donc suivre son dernier horodatage, car un écho est le message du compte et ne prolonge rien. Les réponses rédigées par un agent humain peuvent utiliser la fenêtre Human Agent de Meta, distincte et de 7 jours, à condition de porter le tag human_agent.
Que ne contient pas un événement messages ?
Certaines informations qu'un gestionnaire pourrait chercher sont absentes, selon les références de messagerie de Meta :
- Le nom ou le nom d'utilisateur de la personne : seulement l'ID Instagram-scoped, que GET /<IGSID> résout.
- Les médias à vue unique : ils arrivent sous forme de pièce jointe éphémère, sans URL.
- L'image exacte du carrousel : une réaction à une image d'un carrousel, ou son transfert, signale la première image.
- Les réactions, modifications et accusés de lecture, qui arrivent dans des champs qui leur sont propres.
- Une marque de lecture : un message livré par webhook reste non lu dans la boîte de réception Instagram jusqu'à l'envoi d'une réponse.
Quels autres champs de messagerie Meta liste-t-il ?
Les champs et exemples de Meta pour Instagram Login citent d'autres événements de messagerie, chacun ayant son propre événement. easyCoexistence abonne chaque compte uniquement aux messages, aux commentaires et aux mentions ; aucun de ceux-ci ne fait donc partie de ce qu'il transmet :
message_reactions: une personne réagit à un message ou retire sa réaction, avec reaction.mid, action à react ou unreact, ainsi que la réaction et l'emoji.message_edit: une personne modifie un message, avecmessage_edit.mid, le nouveau texte etnum_edit.messaging_postbacks: une personne touche un icebreaker ou un bouton de template, avec postback.mid, title et payload.messaging_referral: une personne déjà dans une conversation ouvre un lien ig.me avec un paramètre ref.messaging_seen: une personne lit un message, avec read.mid.messaging_optins,messaging_handoveret standby : les deux derniers concernent les applications qui partagent une conversation selon le protocole de transfert de Meta.
Que doit activer le compte ?
Autoriser l'accès aux messages. Meta exige qu'un compte professionnel l'active avant que ses messages puissent être gérés via l'API, dans l'application Instagram sous Paramètres, Messages et réponses aux Stories, Contrôles des messages, Outils connectés. Tant que cette option est désactivée, les envois échouent avec le code 200, sous-code 2534041. L'application a aussi besoin de instagram_business_basic et instagram_business_manage_messages, avec l'Advanced Access pour servir des comptes qu'elle ne possède pas ni ne gère.
Comment easyCoexistence transmet-il un DM ?
Comme un commentaire : chaque entrée que Meta livre pour le compte est envoyée en POST à votre endpoint HTTPS, dans une enveloppe composée de platform, account_id, external_id et entry, signée dans X-EC-Signature avec le secret du compte, une seule fois et sans copie conservée. Les échos sont transmis avec le reste ; vérifiez donc is_echo avant de répondre. Pour répondre, appelez send_social_dm avec l'account_id et le sender.id de l'événement comme recipient_id, dans la fenêtre de 24 heures. Les automatisations déclenchées par un DM s'exécutent sur les mêmes événements.
{
"platform": "instagram",
"account_id": "<ACCOUNT_ID>",
"external_id": "<IG_ID>",
"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": "<URL_FOR_THE_MEDIA>" } }
]
}
}
]
}
}Erreurs courantes
- Répondre aux échos. Un événement avec is_echo défini est le message du compte lui-même, et y répondre enferme le compte dans une boucle avec lui-même.
- Supposer qu'un message contient toujours du texte. Les pièces jointes, partages, mentions de Story et suppressions arrivent sans champ text ; testez donc ce que contient l'objet message.
- Trier les messages selon leur ordre d'arrivée. Meta peut livrer des messages dans le désordre après une panne ; triez-les donc par timestamp.
- Lire time et timestamp en secondes. Les exemples de messagerie de Meta les donnent en millisecondes ; lus en secondes, ils deviennent des dates très éloignées dans le futur.
send_social_dm répond dans la fenêtre de 24 heures, et les automatisations peuvent répondre seules avec un texte fixe ou une IA. De US$ 9 à US$ 0,75 par connexion et par mois, en baisse à mesure que vous ajoutez des connexions, avec un essai gratuit de 3 jours.
Questions fréquemment posées
Les timestamps des webhooks de messages Instagram sont-ils en secondes ou en millisecondes ?
En millisecondes, selon les exemples de messagerie de Meta, pour timestamp comme pour l'heure de l'entrée. Lus en secondes, ils deviennent des dates très éloignées dans le futur.
Comment obtenir le nom d'utilisateur de l'expéditeur d'un DM Instagram via webhook ?
Appelez GET /<IGSID> avec les champs name et username. L'événement ne contient que l'ID Instagram-scoped de la personne.
Pourquoi mes webhooks de DM Instagram n'arrivent-ils pas ?
Vérifiez que le compte a activé Autoriser l'accès aux messages, qu'il est abonné aux messages via /subscribed_apps, et que l'application est Live avec l'Advanced Access pour les comptes qu'elle ne possède pas.
easyCoexistence transmet-il les réactions aux messages Instagram ?
Non. Les réactions arrivent sur message_reactions, et easyCoexistence abonne les comptes aux messages, aux commentaires et aux mentions.
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