Messaging Insights API

Dieses Dokument erläutert die programmatische Erfassung von Kennzahlen zu Nachrichten, die dein Unternehmen gesendet bzw. empfangen hat. Die Messaging Insights API ist eine Erweiterung der Pages Insights API. Du kannst damit dieselben Informationen erfassen wie im Tab „Seiten-Insights“ auf deiner Facebook-Seite.

Bevor du beginnst

Um Kennzahlen für eine Facebook-Seite abzurufen, deren Eigentümer du bist oder für die du die ANALYZE-Aufgabe ausführen kannst, benötigt deine App Folgendes:

• Die Seiten-ID der Facebook-Seite, für die du Kennzahlen einsehen willst

  • Für Instagram-Messaging handelt es sich dabei um die mit dem professionellen Instagram-Konto verknüpfte Facebook-Seite
• Einen Seiten-Zugriffsschlüssel
• Die folgenden Berechtigungen:

  • pages_messaging
  • pages_read_engagement
  • pages_show_list
  • read_insights
• Standardzugriff

Um Kennzahlen für eine Facebook-Seite abzurufen, deren Eigentümer*in du nicht bist oder für welche du die ANALYZE-Aufgabe nicht ausführen kannst, benötigt deine App Folgendes:

• Die Seiten-ID der Facebook-Seite, für die du Kennzahlen einsehen willst

  • Für Instagram-Messaging handelt es sich dabei um die mit dem professionellen Instagram-Konto verknüpfte Facebook-Seite
• Einen Seiten-Zugriffsschlüssel, der von einer Person angefordert wurde, welche die ANALYZE-Aufgabe für die Seite ausführen kann
• Folgende Berechtigungen per Facebook Login:

  • pages_messaging
  • pages_read_engagement
  • pages_show_list
  • read_insights
• Erweiterter Zugriff

Einschränkungen

• Damit neue Unterhaltungen berücksichtigt werden, muss die Person eine Handlung ausgeführt und z. B. deinem Unternehmen geantwortet haben. Bis die Person aktiv wird, ist die Unterhaltung nur für sie sichtbar und wird nicht gezählt.

Insights-Kennzahlen auslesen

Um Informationen zu einer oder mehreren Kennzahlen auszulesen, sende eine GET-Anfrage an den Endpunkt /PAGE-ID/insights. Der metric-Parameter muss dabei eine kommagetrennte Liste der Kennzahlen enthalten, die du einsehen möchtest.

Beispielanfrage

curl -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/insights
    ?metric=page_messages_new_conversations_unique,page_messages_blocked_conversations_unique 
    &access_token=PAGE-ACCESS-TOKEN"

Wenn der Vorgang erfolgreich verläuft, erhält deine App die folgende JSON-Antwort:

{ 
  "data": [ 
    { 
      "name": "page_messages_new_conversations_unique", 
      "period": "day", 
      "values": [ 
        { 
          "value": "42", 
          "end_time": "1665175977" 
        }, 
      ]
    },
    { 
      "name": "page_messages_blocked_conversations_unique", 
      "period": "day", 
      "values": [ 
        { 
          "value": "0", 
          "end_time": "1665175977" 
        }, 
      ]
    } 
  ],
}

Beispielanfrage für Gesamtzahl im Zeitraum

Das folgende Beispiel ermittelt die Gesamtzahl der neuen individuellen Unterhaltungen in einem bestimmten Zeitraum. In unserem API-Aufruf ist dazu der period-Parameter auf total_over_range festgelegt, die Parameter since und until definieren dabei den Zeitraum.

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/insights/
    ?metric=page_messages_new_conversations_unique
    &since=UNIX-TIMESTAMP-START
    &until=UNIX-TIMESTAMP-STOP
    &period=total_over_range
    &access_token=PAGE-ACCESS-TOKEN"

Wenn der Vorgang erfolgreich verläuft, erhält deine App die folgende JSON-Antwort mit der Anzahl der neuen individuellen Unterhaltungen und dem Ende des Zeitraums:

{
  "data": [
    {
      "name": "page_messages_new_conversations_unique",
      "period": "total_over_range",
      "values": [
        {
          "value": 27
          "end_time": "1665175977"
        }
      ],
    }
  ]
}

Beispielanfrage für Aufschlüsselung

Das folgende Beispiel ermittelt die Gesamtzahl wiederkehrender Mitteilungs-Token in einem bestimmten Zeitraum, gruppiert nach Thema und Häufigkeit.

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/insights/
    ?metric=recurring_notifications_tokens   
    &since=UNIX-TIMESTAMP-START
    &until=UNIX-TIMESTAMP-STOP
    &period=total_over_range
    &breakdown=recurring_notifications_topic,recurring_notifications_frequency 
    &access_token=PAGE-ACCESS-TOKEN"

Wenn der Vorgang erfolgreich verläuft, erhält deine App die folgende JSON-Antwort mit Token gruppiert nach Thema („newproducts“ und „10percentsale“) sowie mit der für die einzelnen Themen verfügbaren Nachrichtenfrequenz („daily“, „weekly“ und „monthly“ bei „newproducts“ sowie „daily“ und „weekly“ bei „10percentsale“):

{
  "data": [
    {
      "name": "recurring_notifications_tokens",
      "period": "total_over_range",
      "values": [ 
        {
          "value": 3,
          "end_time": "1665175977",
          "recurring_notifications_topic": "newproducts",
          "recurring_notifications_frequency": "daily"
        },
        {
          "value": 15,
          "end_time": "1665175977",
          "recurring_notifications_topic": "newproducts",
          "recurring_notifications_frequency": "weekly"
        },
        {
          "value": 8,
          "end_time": "1665175977",
          "recurring_notifications_topic": "newproducts",
          "recurring_notifications_frequency": "monthly"
        },
        {
          "value": 17,
          "end_time": "1665175977",
          "recurring_notifications_topic": "10percentsale",
          "recurring_notifications_frequency": "daily"
        },
        {
          "value": 14,
          "end_time": "1665175977",
          "recurring_notifications_topic": "10percentsale",
          "recurring_notifications_frequency": "weekly"
        },
      ]
    }
  ]
}

Insights-Parameter

Verfügbare Metriken

Die folgenden Kennzahlen sind über die Messaging Insights API verfügbar:

Mehr dazu: In Entwicklung befindliche Kennzahlen

Antworteigenschaften

Ein Aufruf der Insights API kann folgende Informationen liefern:

Siehe auch

• Weitere Infos zu Seiten-Insights
• Weitere Infos zur Insights-Objektreferenz