InloggenGratis proefperiode starten
easyCoexistence Officiële API's

Instagram messages-webhook: de DM-payload, echo's en velden

Het messages-veld van Instagram levert de DM's van een professioneel account af zodra ze binnenkomen: tekst, bijlagen, gedeelde berichten, Story-antwoorden en vermeldingen, inline-antwoorden en verwijderingen. Elke gebeurtenis staat in een messaging-array met het Instagram-scoped ID van de afzender, de ontvanger, een tijdstempel en een message-object. Berichten die het account zelf verstuurt, komen via hetzelfde veld terug met is_echo op true.

easyCoexistence abonneert elk verbonden Instagram-account op messages en stuurt de DM's ervan, echo's inbegrepen, door naar je HTTPS-endpoint zodra ze binnenkomen, ondertekend met het geheim van dat account; doorsturen houdt geen kopie bij, en DM's worden standaard niet opgeslagen.

is_echo

Staat op true bij een berichtgebeurtenis voor een bericht dat het account zelf heeft verstuurd.

24 hours

Standaard messaging-venster voor de meeste gebruikersacties, waarin de app de persoon kan antwoorden.

ig_post

Bijlagetype voor een gedeelde post; het oude share-type werd alleen ondersteund tot 1 februari 2026.

story_mention

Bijlagetype van de DM-gebeurtenis die Meta verstuurt wanneer iemand het account in zijn Story vermeldt.

2534041

Foutsubcode, onder code 200, wanneer de accounteigenaar de toegang tot Instagram-directberichten heeft uitgeschakeld.

Wanneer vuurt het messages-veld?

Wanneer iemand het professionele account een DM stuurt, en wanneer het account er zelf een stuurt. De voorbeelden en referenties van Meta noemen deze gevallen, elk als messaging-gebeurtenis met een message-object:

  • Tekst, en media als bijlagen: afbeeldingen, video, audio en bestanden.
  • Een gedeelde post of Reel, als bijlage van het type ig_post, ig_reel of reel.
  • Een antwoord op een Story van het account, met reply_to.story, en een Story die het account vermeldt, als bijlage van het type story_mention.
  • Een inline-antwoord op een eerder bericht, met reply_to.mid, en een quick reply, met quick_reply.payload.
  • Een bericht dat de persoon heeft verwijderd (is_deleted), niet-ondersteunde media (is_unsupported), en een bericht van iemand die op een Click-to-Direct-advertentie heeft geklikt (referral).
  • Een bericht dat het account heeft verstuurd, dat met is_echo op true terugkomt.

Hoe ziet een messages-melding eruit?

Een POST waarvan de JSON object op instagram heeft staan. Anders dan bij een reactie zit een bericht in een messaging-array binnen de entry van het account, en elk element bevat sender, recipient, timestamp en message. Een antwoord op een Story van het account ziet er zo uit:

A messages notification, 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>",
            "text": "<MESSAGE_TEXT>",
            "reply_to": {
              "story": {
                "url": "<CDN_URL_FOR_THE_STORY>",
                "id": "<STORY_ID>"
              }
            }
          }
        }
      ]
    }
  ]
}

Wat betekent elk veld?

De velden die Meta documenteert voor een berichtgebeurtenis onder Instagram Login, van buiten naar binnen:

  • entry[].id: het ID van het professionele account. entry[].time: wanneer Meta de melding verstuurde; de messaging-voorbeelden van Meta geven dat in milliseconden.
  • sender.id en recipient.id: bij een binnenkomende DM het Instagram-scoped ID van de persoon en het ID van het account; bij een echo precies andersom.
  • timestamp: wanneer het bericht is verstuurd, in milliseconden in de voorbeelden van Meta. Sorteer berichten hierop, niet op volgorde van aankomst.
  • message.mid: het bericht-ID, om dubbelen te herkennen, op te reageren en met reply_to.mid op dat bericht te antwoorden.
  • message.text: aanwezig wanneer het bericht tekst bevat.
  • message.attachments[]: elk met een type en een payload, meestal een url. De ig_post-payload van een gedeelde post voegt ig_post_media_id en title toe, het bijschrift.
  • message.reply_to: mid bij een inline-antwoord, of story met de url en het id van de Story bij een Story-antwoord.
  • message.quick_reply.payload en message.referral: de gekozen quick reply, en de ref, ad_id, source, type en ads_context_data van de Click-to-Direct-advertentie.
  • message.is_deleted, is_echo, is_self en is_unsupported: alleen aanwezig wanneer ze true zijn.
  • message.admin_text en handoff_reason: bij in aanmerking komende apps een melding dat een Meta-toepassing, zoals Meta Business Agent, het gesprek heeft overgedragen; die kan komen zonder mid of tekst.

Hoe werken echo's?

Wanneer het account een bericht verstuurt, stuurt Meta er ook een messages-gebeurtenis voor, met is_echo op true. sender.id is dan het account en recipient.id het Instagram-scoped ID van de persoon. Een testbericht dat het account naar zichzelf stuurt, heeft ook is_self. Echo's leggen vast wat het account zei, wat een gespreksoverzicht nodig heeft, maar een handler die beslist of hij antwoordt, moet ze overslaan. Meta stuurt geen echo wanneer het account op een bericht reageert of een reactie verwijdert.

An echo of a message the account sent
{
  "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
          }
        }
      ]
    }
  ]
}

Welk ID gebruik je om te antwoorden?

sender.id, het Instagram-scoped ID van de persoon. Meta maakt het aan wanneer iemand het account een bericht stuurt of op zijn media reageert, en het is specifiek voor die persoon en dat account. POST /<IG_ID>/messages met recipient.id ingesteld op dit ID verstuurt het antwoord. De gebeurtenis bevat geen naam of gebruikersnaam; GET /<IGSID> met velden als name en username levert die wel, omdat een persoon die het account een bericht heeft gestuurd de toestemming heeft gegeven die deze opvraging nodig heeft.

Hoe opent een bericht het 24-uursvenster?

Een app kan een persoon alleen berichten nadat die het account een bericht heeft gestuurd, en alleen binnen het standaard messaging-venster dat hun actie opent. Voor de meeste acties duurt dat 24 uur, en tot 7 dagen na een eerste bericht dat is verstuurd na een klik op een Click-to-Direct-advertentie. Een nieuw bericht van de persoon opent een nieuw venster, dus hun laatste timestamp is die je moet bijhouden; een echo is het eigen bericht van het account en verlengt niets. Antwoorden die door een mens worden geschreven, kunnen gebruikmaken van het aparte Human Agent-venster van 7 dagen van Meta, gelabeld met human_agent.

Wat bevat een messages-gebeurtenis niet?

Een paar zaken die een handler misschien zoekt, ontbreken volgens de berichtenreferenties van Meta:

  • De naam of gebruikersnaam van de persoon: alleen het Instagram-scoped ID, dat GET /<IGSID> omzet.
  • Eenmalig bekijkbare media: die komt als ephemeral-bijlage zonder URL.
  • De exacte carrousel-afbeelding: een reactie op of een doorgestuurd bericht van één afbeelding uit een carrouselpost meldt de eerste afbeelding.
  • Reacties, bewerkingen en leesbevestigingen, die via eigen velden komen.
  • Een leesmarkering: een bericht dat via webhook is afgeleverd, blijft ongelezen in de Instagram-inbox tot er een antwoord is verstuurd.

Welke andere berichtvelden noemt Meta?

De veldlijst en voorbeelden van Meta voor Instagram Login noemen daarnaast deze, elk een eigen messaging-gebeurtenis. easyCoexistence abonneert elk account alleen op messages, comments en mentions, dus geen van deze maakt deel uit van wat het doorstuurt:

  • message_reactions: een persoon reageert op een bericht of verwijdert de reactie, met reaction.mid, action ingesteld op react of unreact, en de reaction en emoji.
  • message_edit: een persoon bewerkt een bericht, met message_edit.mid, de nieuwe tekst en num_edit.
  • messaging_postbacks: een persoon tikt op een icebreaker of een templateknop, met postback.mid, title en payload.
  • messaging_referral: een persoon die al in een gesprek zit, opent een ig.me-link met een ref-parameter.
  • messaging_seen: een persoon leest een bericht, met read.mid.
  • messaging_optins, messaging_handover en standby: de laatste twee voor apps die een gesprek delen onder het handover-protocol van Meta.

Wat moet het account aanzetten?

Sta toegang tot berichten toe. Meta vereist dat een professioneel account dit aanzet voordat de berichten ervan via de API beheerd kunnen worden, in de Instagram-app onder Instellingen, Berichten en Story-antwoorden, Berichtbeheer, Verbonden tools. Zolang dit uit staat, mislukken verzendingen met code 200, subcode 2534041. De app heeft ook instagram_business_basic en instagram_business_manage_messages nodig, met Advanced Access om accounts te bedienen die het niet bezit of beheert.

Hoe stuurt easyCoexistence een DM door?

Net als een reactie: elke entry die Meta voor het account levert, wordt als POST naar je HTTPS-endpoint gestuurd, in een envelop met platform, account_id, external_id en entry, ondertekend in X-EC-Signature met het geheim van het account, eenmalig en zonder kopie te bewaren. Echo's worden met de rest doorgestuurd, dus controleer is_echo voordat je antwoordt. Om te antwoorden roep je send_social_dm aan met het account_id en de sender.id van de gebeurtenis als recipient_id, binnen het 24-uursvenster. Automatiseringen die bij een DM starten, draaien op dezelfde gebeurtenissen.

A forwarded DM with an image
{
  "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>" } }
          ]
        }
      }
    ]
  }
}

Veelgemaakte fouten

  • Reageren op echo's. Een gebeurtenis met is_echo is het eigen bericht van het account, en een antwoord erop stuurt het account in een lus met zichzelf.
  • Aannemen dat een bericht altijd tekst heeft. Bijlagen, gedeelde berichten, Story-vermeldingen en verwijderingen komen zonder tekstveld, dus vertak op wat het message-object bevat.
  • Berichten sorteren op volgorde van aankomst. Meta kan berichten na een storing door elkaar afleveren, dus sorteer ze op timestamp.
  • time en timestamp als seconden verwerken. De messaging-voorbeelden van Meta geven beide in milliseconden, en gelezen als seconden worden het datums ver in de toekomst.
Dit doen met EasyCoexistence

send_social_dm antwoordt binnen het 24-uursvenster, en automatiseringen kunnen zelfstandig antwoorden met een vaste tekst of met AI. US$ 9 tot US$ 0,75 per verbinding per maand, dalend naarmate je verbindingen toevoegt, met de eerste 3 dagen als gratis proefperiode.

Veelgestelde vragen

Zijn de tijdstempels van de Instagram messages-webhook in seconden of milliseconden?

In milliseconden, volgens de messaging-voorbeelden van Meta, voor zowel timestamp als de tijd van de entry. Gelezen als seconden worden ze datums ver in de toekomst.

Hoe krijg ik de gebruikersnaam van de afzender uit een Instagram-DM-webhook?

Roep GET /<IGSID> aan met velden als name en username. De gebeurtenis bevat alleen het Instagram-scoped ID van de persoon.

Waarom komen mijn Instagram-DM-webhooks niet aan?

Controleer of het account Sta toegang tot berichten toe heeft aangezet, of de app via /subscribed_apps is geabonneerd op messages, en of de app Live is met Advanced Access voor accounts die ze niet bezit.

Stuurt easyCoexistence Instagram-berichtreacties door?

Nee. Reacties komen via message_reactions, en easyCoexistence abonneert accounts op messages, comments en mentions.

Lees verder

Koppel je eerste kanaal in twee minuten.

Geen platformbeoordelingen om op te wachten. Verbind WhatsApp, Instagram, TikTok of een ander kanaal, vraag je AI om te posten, te reageren of een rapport te maken, en zie het aan het werk.

  • 3 dagen gratis
  • Op elk moment opzegbaar
  • Alleen officiële API's
  • 24/7 bewaakt

Geverifieerd op