AnmeldenKostenlose Testphase starten
easyCoexistence Offizielle APIs

Instagram-Nachrichten-Webhook: DM-Payload, Echos und Felder

Das messages-Feld des Instagram-Webhooks liefert die DMs eines professionellen Kontos, sobald sie eintreffen: Text, Anhänge, geteilte Beiträge, Story-Antworten und Erwähnungen, Inline-Antworten und Löschungen. Jedes Ereignis steht in einem messaging-Array mit der Instagram-scoped ID des Absenders, dem Empfänger, einem Zeitstempel und einem message-Objekt. Vom Konto selbst gesendete Nachrichten kommen über dasselbe Feld zurück, mit is_echo auf true gesetzt.

easyCoexistence abonniert jedes verbundene Instagram-Konto für messages und leitet dessen DMs, einschließlich Echos, sobald sie eintreffen, an Ihren HTTPS-Endpoint weiter, signiert mit dem Secret dieses Kontos.

is_echo

Auf true gesetzt bei einem Nachrichten-Ereignis für eine Nachricht, die das Konto selbst gesendet hat.

24 hours

Standard-Messaging-Fenster für die meisten Nutzeraktionen, in dem die App der Person antworten kann.

ig_post

Anhangstyp für einen geteilten Beitrag; der alte share-Typ wurde nur bis zum 1. Februar 2026 unterstützt.

story_mention

Anhangstyp des DM-Ereignisses, das Meta sendet, wenn jemand das Konto in seiner Story erwähnt.

2534041

Fehler-Subcode unter Code 200, wenn der Kontoinhaber den Zugriff auf Instagram-Direktnachrichten deaktiviert hat.

Wann feuert das messages-Feld?

Wenn eine Person dem professionellen Konto eine DM sendet und wenn das Konto selbst eine sendet. Die Beispiele und Referenzen von Meta listen diese Fälle auf, jeweils als messaging-Ereignis mit einem message-Objekt:

  • Text sowie Medien als Anhänge: Bilder, Videos, Audio und Dateien.
  • Ein geteilter Beitrag oder Reel, als Anhang vom Typ ig_post, ig_reel oder reel.
  • Eine Antwort auf die Story des Kontos, mit reply_to.story, und eine Story, die das Konto erwähnt, als Anhang vom Typ story_mention.
  • Eine Inline-Antwort auf eine frühere Nachricht, mit reply_to.mid, und eine Schnellantwort, mit quick_reply.payload.
  • Eine Nachricht, die die Person gelöscht hat (is_deleted), nicht unterstützte Medien (is_unsupported) und eine Nachricht von jemandem, der auf eine Click-to-Direct-Anzeige geklickt hat (referral).
  • Eine Nachricht, die das Konto gesendet hat; sie kommt mit is_echo auf true zurück.

Wie sieht eine Benachrichtigung über Nachrichten aus?

Ein POST, dessen JSON object auf instagram gesetzt ist. Anders als bei einem Kommentar steht eine Nachricht in einem messaging-Array innerhalb des entry des Kontos, und jedes Element enthält sender, recipient, timestamp und message. Eine Antwort auf die Story des Kontos sieht so aus:

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>"
              }
            }
          }
        }
      ]
    }
  ]
}

Was bedeutet jedes Feld?

Die Felder, die Meta für ein Nachrichten-Ereignis unter Instagram Login dokumentiert, von außen nach innen:

  • entry[].id: die ID des professionellen Kontos. entry[].time: wann Meta die Benachrichtigung gesendet hat; die Nachrichtenbeispiele von Meta geben sie in Millisekunden an.
  • sender.id und recipient.id: bei einer eingehenden DM die Instagram-scoped ID der Person und die ID des Kontos; bei einem Echo dieselben beiden in umgekehrter Reihenfolge.
  • timestamp: wann die Nachricht gesendet wurde, in den Beispielen von Meta in Millisekunden. Sortieren Sie Nachrichten danach, nicht nach Eingangsreihenfolge.
  • message.mid: die Nachrichten-ID, zum Deduplizieren, Reagieren und Antworten auf diese Nachricht mit reply_to.mid.
  • message.text: enthalten, wenn die Nachricht Text enthält.
  • message.attachments[]: jeweils mit einem type und einem payload, meist eine url. Der payload eines geteilten Beitrags vom Typ ig_post ergänzt ig_post_media_id und title, seine Bildunterschrift.
  • message.reply_to: mid bei einer Inline-Antwort, oder story mit der url und id der Story bei einer Story-Antwort.
  • message.quick_reply.payload und message.referral: die gewählte Schnellantwort sowie die ref, ad_id, source, type und ads_context_data der Click-to-Direct-Anzeige.
  • message.is_deleted, is_echo, is_self und is_unsupported: nur enthalten, wenn true.
  • message.admin_text und handoff_reason: bei berechtigten Apps eine Mitteilung, dass eine Meta-Anwendung, etwa Meta Business Agent, die Konversation übergeben hat; sie kann ohne mid oder text eintreffen.

Wie funktionieren Echos?

Wenn das Konto eine Nachricht sendet, schickt Meta dafür ebenfalls ein Nachrichten-Ereignis, mit is_echo auf true. sender.id ist dann das Konto und recipient.id die Instagram-scoped ID der Person; eine Testnachricht, die das Konto an sich selbst sendet, trägt außerdem is_self. Echos halten fest, was das Konto gesagt hat, was ein Gesprächsprotokoll braucht, aber ein Handler, der entscheidet, ob er antwortet, muss sie überspringen. Meta sendet kein Echo, wenn das Konto auf eine Nachricht reagiert oder eine Reaktion entfernt.

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
          }
        }
      ]
    }
  ]
}

Welche ID nutzen Sie für eine Antwort?

sender.id, die Instagram-scoped ID der Person. Meta erstellt sie, wenn jemand dem Konto schreibt oder einen Beitrag des Kontos kommentiert; sie ist für diese Person und dieses Konto spezifisch. POST /<IG_ID>/messages mit recipient.id auf diesen Wert sendet die Antwort. Das Ereignis enthält keinen Namen und keinen Benutzernamen; GET /<IGSID> mit Feldern wie name und username liefert sie, weil eine Person, die dem Konto geschrieben hat, die Einwilligung erteilt hat, die diese Abfrage braucht.

Wie öffnet eine Nachricht das 24-Stunden-Fenster?

Eine App darf einer Person nur schreiben, nachdem diese dem Konto geschrieben hat, und nur innerhalb des Standard-Messaging-Fensters, das ihre Aktion öffnet. Für die meisten Aktionen gilt es 24 Stunden, bei einer ersten Nachricht nach einem Klick auf eine Click-to-Direct-Anzeige bis zu 7 Tage. Eine neue Nachricht der Person öffnet ein neues Fenster, daher ist ihr letzter Zeitstempel der nachzuverfolgende Wert; ein Echo ist die eigene Nachricht des Kontos und verlängert nichts. Antworten, die eine Person schreibt, können das separate 7-Tage-Fenster Human Agent von Meta nutzen, gekennzeichnet mit human_agent.

Was enthält ein Nachrichten-Ereignis nicht?

Einige Dinge, die ein Handler suchen könnte, fehlen laut den Nachrichten-Referenzen von Meta:

  • Name oder Benutzername der Person: nur die Instagram-scoped ID, die GET /<IGSID> auflöst.
  • Einmalig ansehbare Medien: sie kommen als flüchtiger Anhang ohne URL.
  • Das genaue Karussellbild: eine Reaktion auf oder eine Weiterleitung eines Bildes in einem Karussell-Beitrag meldet das erste Bild.
  • Reaktionen, Bearbeitungen und Lesebestätigungen: sie haben eigene Felder.
  • Eine Lesemarkierung: eine per Webhook zugestellte Nachricht bleibt im Instagram-Posteingang ungelesen, bis eine Antwort gesendet wird.

Welche weiteren Nachrichtenfelder listet Meta?

Metas Feldliste und Beispiele für Instagram Login nennen außer messages diese, jeweils als eigenes Nachrichten-Ereignis. easyCoexistence abonniert jedes Konto nur für messages, comments und mentions, daher ist keines davon Teil dessen, was es weiterleitet:

  • message_reactions: eine Person reagiert auf eine Nachricht oder entfernt die Reaktion, mit reaction.mid, action auf react oder unreact sowie reaction und emoji.
  • message_edit: eine Person bearbeitet eine Nachricht, mit message_edit.mid, dem neuen Text und num_edit.
  • messaging_postbacks: eine Person tippt auf einen Icebreaker oder einen Template-Button, mit postback.mid, title und payload.
  • messaging_referral: eine Person, die bereits in einer Konversation ist, öffnet einen ig.me-Link mit einem ref-Parameter.
  • messaging_seen: eine Person liest eine Nachricht, mit read.mid.
  • messaging_optins, messaging_handover und standby: die beiden letzten für Apps, die eine Konversation nach Metas Handover-Protokoll teilen.

Was muss das Konto aktivieren?

Allow access to messages. Meta verlangt, dass ein professionelles Konto diese Option aktiviert, bevor seine Nachrichten über die API verwaltet werden können. In der Instagram-App unter Settings, Messages and story replies, Message controls, Connected tools. Solange sie deaktiviert ist, schlagen Sendungen mit Code 200, Subcode 2534041 fehl. Die App braucht außerdem instagram_business_basic und instagram_business_manage_messages, mit Advanced Access, um Konten zu bedienen, die sie nicht besitzt oder verwaltet.

Wie leitet easyCoexistence eine DM weiter?

Wie bei einem Kommentar: Jedes Ereignis, das Meta für das Konto zustellt, wird als POST an Ihren HTTPS-Endpoint gesendet, in einem Umschlag mit platform, account_id, external_id und entry. Es ist in X-EC-Signature mit dem Secret des Kontos signiert, einmal, und es wird keine Kopie gespeichert. Echos werden mit dem Rest weitergeleitet, prüfen Sie daher is_echo, bevor Sie antworten. Zum Antworten rufen Sie send_social_dm mit der account_id auf und der sender.id des Ereignisses als recipient_id, innerhalb des 24-Stunden-Fensters. Automatisierungen, die bei einer DM starten, laufen auf denselben Ereignissen.

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>" } }
          ]
        }
      }
    ]
  }
}

Häufige Fehler

  • Auf Echos antworten. Ein Ereignis mit gesetztem is_echo ist die eigene Nachricht des Kontos, und eine Antwort darauf schickt das Konto in eine Schleife mit sich selbst.
  • Annehmen, eine Nachricht habe immer Text. Anhänge, geteilte Beiträge, Story-Erwähnungen und Löschungen kommen ohne Textfeld, daher verzweigen Sie anhand dessen, was das message-Objekt enthält.
  • Nachrichten nach Eingangsreihenfolge sortieren. Meta kann Nachrichten nach einem Fehler außer der Reihe zustellen, sortieren Sie sie daher nach timestamp.
  • time und timestamp als Sekunden lesen. Die Nachrichtenbeispiele von Meta geben beides in Millisekunden an; als Sekunden gelesen werden daraus Daten weit in der Zukunft.
Mit EasyCoexistence

Die Weiterleitung speichert keine Kopie, und DMs werden standardmäßig nicht gespeichert. send_social_dm antwortet innerhalb des 24-Stunden-Fensters, und Automatisierungen können mit einem festen Text oder mit KI selbstständig antworten. US$ 9 bis US$ 0.75 pro Verbindung und Monat, sinkend mit jeder weiteren Verbindung, mit einer kostenlosen Testphase von 3 Tagen.

Häufig gestellte Fragen

Sind Zeitstempel von Instagram-Nachrichten-Webhooks in Sekunden oder Millisekunden?

In Millisekunden, laut den Nachrichtenbeispielen von Meta, sowohl für timestamp als auch für die Zeit des entry. Als Sekunden gelesen werden sie zu Daten weit in der Zukunft.

Wie erhalte ich den Benutzernamen des Absenders aus einer Instagram-DM per Webhook?

Rufen Sie GET /<IGSID> mit Feldern wie name und username auf. Das Ereignis enthält nur die Instagram-scoped ID der Person.

Warum kommen meine Instagram-DM-Webhooks nicht an?

Prüfen Sie, ob das Konto Zugriff auf Nachrichten zulassen aktiviert hat, ob es über /subscribed_apps für messages abonniert ist und ob die App mit Advanced Access live ist, für Konten, die sie nicht besitzt.

Leitet easyCoexistence Instagram-Nachrichtenreaktionen weiter?

Nein. Reaktionen kommen über message_reactions, und easyCoexistence abonniert Konten für messages, comments und mentions.

Weiterlesen

Verbinden Sie Ihren ersten Kanal in zwei Minuten.

Keine Plattform-Prüfungen, auf die Sie warten müssen. Verbinden Sie WhatsApp, Instagram, TikTok oder einen anderen Kanal, bitten Sie dann Ihre KI, zu posten, zu antworten oder Berichte zu erstellen, und sehen Sie ihr bei der Arbeit zu.

  • 3 Tage kostenlos
  • Jederzeit kündbar
  • Nur offizielle APIs
  • Überwacht rund um die Uhr (24/7)

Verifiziert am