Einrichten von Webhooks für Instagram

Mit Webhooks für Instagram erhältst du in Echtzeit Benachrichtigungen, wenn jemand die Medienobjekte deiner App-Nutzer*innen kommentiert oder deine App-Nutzer*innen @erwähnt sowie wenn Stories deiner App-Nutzer*innen ablaufen.

Live-Webhook-Benachrichtigungen erhalten

Damit du Live-Webhook-Benachrichtigungen erhältst, müssen folgende Bedingungen erfüllt sein:

Für deine App müssen Instagram-Webhooks konfiguriert und entsprechende Felder im App Dashboard abonniert sein.
Verbraucher-Apps müssen im Live-Modus sein.
Business-Apps müssen über Berechtigungen au der Ebene Advanced Access verfügen. Advanced Access für Berechtigungen forderst du wie folgt an:

Wenn die App-Berechtigungen nicht auf der Zugriffsebene Advanced Access erteilt wurden, erhält die App keine Webhook-Benachrichtigungen.

App-Nutzer*innen müssen deiner App entsprechende Berechtigungen (instagram_manage_insights für Stories, instagram_manage_comments für Kommentare und @Erwähnungen) erteilt haben.
Für die Seite, die mit dem Konto des*der App-Nutzer*in verknüpft ist, müssen Seitenabonnements aktiviert sein.
Das mit der Seite des App-Nutzers verknüpfte Unternehmen muss verifiziert sein.
Der Besitzer des Medienobjekts, auf dem der Kommentar bzw. die @Mention erscheint, darf sein Konto nicht auf privat eingestellt haben.

Einschränkungen

Webhooks-Benachrichtigungen für Kommentare zu Alben enthalten keine Album-ID. Frage zum Abrufen der Album-ID die Kommentar-ID im Webhook an und fordere deren media-Feld an.
Apps erhalten Webhook-Benachrichtigungen, wenn Medien, unter denen der Kommentar oder die @Erwähnung erscheint, von einem privaten Konto erstellt wurden.
Metriken für Story-Insights mit einem geringeren Wert als 5 werden mit -1 zurückgegeben.
Apps erhalten nur Webhook-Benachrichtigungen oder Kommentare zu Live-IG-Medien, wenn die Medien übertragen werden.
Reels werden nicht unterstützt.
Deine App muss den App Review (für erweiterten Zugriff) erfolgreich durchlaufen haben, um Webhook-Benachrichtigungen für die Webhook-Felder comments und live_comments empfangen zu können.
Wenn die Medien für Dynamic Ads verwendet werden, wird die Anzeigen-ID nicht zurückgegeben.

Schritt 1: Einen Endpunkt erstellen

Erstelle einen Endpunkt, der Webhooks empfängt und verarbeitet. Wähle bei der Konfiguration das Instagram Graph API-Objekt aus und klicke auf Einrichtung. Abonniere mindestens ein Instagram-Feld.

Instagram-Felder

Feld	Beschreibung	Erforderliche Berechtigungen
`comments`	Kommentare zu IG-Medien, die Instagram-Nutzer*innen deiner App besitzen. Die `ad_id`, der `ad_title` und die `original_media_id` werden im media-Objekt zurückgegeben, wenn eine Person einen beworbenen Instagram-Beitrag oder einen Instagram-Werbebeitrag kommentiert.	instagram_manage_comments pages_manage_metadata pages_read_engagementor pages_show_list
`live_comments`	Kommentare zu Live-IG-Medien, die Instagram-Nutzer deiner App besitzen.	instagram_manage_comments pages_manage_metadata pages_read_engagementor pages_show_list
`mentions`	@Erwähnungen für die Instagram-Nutzer deiner App.	instagram_manage_comments pages_manage_metadata pages_read_engagementor pages_show_list
`story_insights`	Kennzahlen, die Interaktionen zu einer Story beschreiben. Werden eine Stunde nach Ablauf einer Story gesendet.	instagram_manage_insights pages_manage_metadata pages_read_engagementor pages_show_list

Schritt 2: Seitenabonnements aktivieren

Deine App muss die Seitenabonnements auf der Seite aktivieren, die mit dem Konto des*der App-Nutzer*in verknüpft ist. Hierzu wird eine POST-Anfrage an die Page Subscribed Apps-Edge gesendet und werden alle Seitenfelder abonniert.

Anforderungen an den Endpunkt

Der Nutzer-Zugriffsschlüssel des App-Nutzers
pages_manage_metadata

Anfragesyntax

POST /{page-id}/subscribed_apps
  ?access_token={access-token}
  &subscribed_fields={fields}

Anfrageparameter

Werteplatzhalter	Wertbeschreibung
`{page_id}`	ID der mit dem Konto desder App-Nutzerin verknüpften Seite.
`{access_token}`	Der Nutzer-Zugriffsschlüssel des App-Nutzers
`{fields}`	Ein Seiten-Feld (z. B. `feed`).

Deine App erhält keine Benachrichtigungen über Änderungen in diesem Feld, es sei denn, du konfigurierst Seiten-Abonnements im App-Dashboard und abonnierst dieses Feld.

Beispielanfrage

curl -i -X POST \
  "https://graph.facebook.com/v24.0/1755847768034402/subscribed_apps?subscribed_fields=feed&access_token=EAAFB..."

Beispielantwort

{
  "success": true
}

Häufige Anwendungsfälle

Erfassen von Story-Insights

Wenn du das story_insights-Feld abonnierst, senden wir deinem Endpunkt eine Webhook-Benachrichtigung mit Kennzahlen zu Nutzer*inneninteraktionen für eine Story, nachdem die Story abgelaufen ist.

Beispiel für eine Story-Insights-Payload

[
  {
    "entry": [
      {
        "changes": [
          {
            "field": "story_insights",
            "value": {
              "media_id": "18023345989012587",
              "exits": 1,
              "replies": 0,
              "reach": 17,
              "taps_forward": 12,
              "taps_back": 0,
              "impressions": 28
            }
          }
        ],
        "id": "17841405309211844",  // Instagram Business or Creator Account ID
        "time": 1547687043
      }
    ],
    "object": "instagram"
  }
]

Antworten auf Kommentar-@Erwähnungen

Wenn du das mentions-Feld abonnierst, senden wir deinem Endpunkt eine Webhook-Benachrichtigung, wenn ein*e Instagram-Nutzer*in ein Instagram Business- oder Creator-Konto in einem Kommentar oder einer Bildunterschrift @erwähnt.

Hier siehst du ein Beispiel für eine Webhook-Benachrichtigungs-Payload für ein Kommentar, die für ein Instagram Business-Konto gesendet wurde (17841405726653026):

Beispiel für eine Payload für eine Kommentar-@Erwähnung

[
  {
    "entry": [
      {
        "changes": [
          {
            "field": "mentions",
            "value": {
              "comment_id": "17894227972186120",  // ID of the comment in which your app user's Instagram professional account was mentioned
              "media_id": "17918195224117851"     // ID of the media the Instagram user commented on
            }
          }
        ],
        "id": "17841405726653026",   // ID of your app user's Instagram professional account
        "time": 1520622968           // Time the notification was sent
      }
    ],
    "object": "instagram"
  }
]

Den Inhalt des Kommentars abrufen

Frag zum Abrufen des Kommentarinhalts mithilfe der Eigenschaft comment_id die GET /{ig-user-id}/mentioned_comment-Edge ab.

Beispielabfrage

GET https://graph.facebook.com/17841405726653026 ?fields=mentioned_comment.comment_id(17894227972186120)

Beispielantwort

{
  "mentioned_comment": {
    "timestamp": "2018-03-20T00:05:29+0000",
    "text": "@bluebottle challenge?",
    "id": "17894227972186120"
  },
  "id": "17841405726653026"
}

Payload und Antwort analysieren

Wenn du die Antwort erhältst, analysiere die Payload für die Eigenschaft text, um festzustellen, ob du auf den Kommentar antworten möchtest. Verwende zum Antworten die Eigenschaftswerte caption_id und media_id der Payload für die Webhook-Benachrichtigung, um den POST /{ig-user-id}/mentions-Endpunkt abzufragen:

Beispielabfrage

curl -i -X POST \
  -d "comment_id=17894227972186120" \
  -d "media_id=17918195224117851" \
  -d "message=Challenge%20accepted!" \
  -d "access_token={access-token}" \
  "https://graph.facebook.com/17841405726653026/mentions"

Beispielantwort

{
  "id": "17911496353086895"
}

Antworten auf Bildunterschrift-@Erwähnungen

Wenn du das mentions-Feld abonnierst, senden wir jedes Mal eine Webhook-Benachrichtigung an deinen Endpunkt, wenn ein*e Nutzer*in ein Instagram Business- oder Creator-Konto in einem Kommentar oder einer Bildunterschrift zu einem Medienobjekt @erwähnt, das nicht dem Unternehmen oder dem Creator gehört.

Hier ist ein Beispiel für eine Webhook-Benachrichtigungs-Payload für eine Bildunterschrift-@Erwähnung für ein Instagram Business-Konto (17841405726653026):

Beispiel einer Webhook-Benachrichtigung zu einer Bildunterschrift-@Erwähnung

[
  {
    "entry": [
      {
        "changes": [
          {
            "field": "mentions",
            "value": {
              "media_id": "17918195224117851"   // ID of the media where your app user's Instagram professional account was mentioned
            }
          }
        ],
        "id": "17841405726653026",   // ID of your app user's Instagram professional account
        "time": 1520622968           // The time Meta sent the notification
      }
    ],
    "object": "instagram"
  }
]

Den Inhalt der Bildunterschrift abrufen

Frag zum Abrufen des Inhalts der Bildunterschrift mithilfe der Eigenschaft media_id die GET /{ig-user-id}/mentioned_media-Edge ab:

Beispielabfrage

GET https://graph.facebook.com/17841405726653026 ?fields=mentioned_media.media_id(17918195224117851){caption,media_type}

Beispielantwort

{
  "mentioned_media": {
    "caption": "@bluebottle There can be only one!",
    "media_type": "IMAGE",
    "id": "17918195224117851"
  },
  "id": "17841405726653026"
}

Payload und Antwort analysieren

Wenn du die Antwort erhältst, analysiere die Payload für die Eigenschaft caption, um festzustellen, ob du auf den Kommentar antworten möchtest. Verwende zum Antworten die Eigenschaft media_id der Payload der Webhook-Benachrichtigung, um die POST /{ig-user-id}/mentions-Edge abzufragen:

Beispielabfrage

curl -i -X POST \
  -d "media_id=17918195224117851" \
  -d "message=MacLeod%20agrees!" \
  -d "access_token={access-token}" \
  "https://graph.facebook.com/17841405726653026/mentions"

Beispielantwort

{
  "id": "17911496353086895"
}