Messenger-Plattform

Conversations API für die Messenger-Plattform

In diesem Dokument wird erklärt, wie du Informationen über deine Messenger- und Instagram-Messaging-Unterhaltungen erhältst. Du kannst Folgendes abrufen:

  • Eine Liste der Unterhaltungen für deine Facebook-Seite oder dein professionelles Instagram-Konto
  • Eine Liste von Nachrichten in jeder Unterhaltung
  • Details zu jeder Nachricht, z. B. wann und von wem die Nachricht gesendet wurde

Bevor du beginnst

Dieses Tutorial setzt voraus, dass du die Übersicht über die Messenger-Plattform und die Übersicht über Instagram Messaging gelesen und die erforderlichen Komponenten implementiert hast.

Voraussetzungen:

  • Die ID für deine Facebook-Seite für dein Unternehmen oder die Facebook-Seite, die mit deinem professionellen Instagram-Konto verknüpft ist
  • Ein Seiten-Zugriffsschlüssel, der von einer Person angefordert wurde, die auf der Seite die Aufgaben MESSAGING oder MODERATE ausführen kann
  • Erweiterter Zugriff ist erforderlich, um auf Unterhaltungen zwischen deinem Unternehmen und Personen zuzugreifen, die keine Rolle in deiner Messaging-App, deinem professionellen Instagram-Konto, deiner Facebook-Seite oder deinem Unternehmen haben

Für Messenger-Unterhaltungen zwischen Personen und deiner Seite benötigt deine App Folgendes:

Für Instagram-Messaging-Unterhaltungen zwischen Personen und deinem professionellen Instagram-Konto benötigt deine App Folgendes:

  • Ein Seiten-Zugriffsschlüssel, der von einer Person angefordert wurde, die die Aufgabe MESSAGING auf der Seite ausführen kann, die mit deinem Instagram Business-Konto verknüpft ist
  • Die Berechtigungen instagram_basic, instagram_manage_messages und pages_manage_metadata
  • Deine App muss einem verifizierten Unternehmen gehören

Einschränkungen

  • Nur die Bild- oder Video-URL für eine Freigabe ist in den Daten enthalten, die bei einem Aufruf der API oder in der Webhook-Benachrichtigung zurückgegeben werden.
  • Wenn deine Konten mit privaten Schlüsseln verknüpft sind, z. B. mit einer E-Mail oder einer Telefonnummer, kannst du die Unterhaltungen zwischen diesen Konten nicht abrufen. Es sind nur Unterhaltungen zwischen einem*einer Facebook-Nutzer*in und einem Instagram-Konto verfügbar. Dieses Problem wird behoben, wenn deine App für erweiterten Zugriff genehmigt wurde. Wenn du in der Kontenübersicht in der Instagram-App mehrere Konten verknüpft hast, kannst du Unterhaltungen zwischen allen verknüpften Konten abrufen.
  • Unterhaltungen im Anfragen-Ordner, die seit 30 Tagen nicht aktiv gewesen sind, werden in API-Aufrufen nicht zurückgegeben.

Du kannst diese API nutzen, um eine Postfachsynchronisierung für frühere Unterhaltungen durchzuführen, wenn ein Instagram Business-Konto zum ersten Mal mit deiner App verbunden wird.

Eine Liste mit Unterhaltungen abrufen

Um eine Liste mit Nachrichten in einer Unterhaltung abzurufen, sende eine GET-Anfrage an den Endpunkt /PAGE-ID/conversations und schließe den Parameter platform ein, der auf instagram oder messenger festgelegt ist.

Beispielanfrage

Für Lesbarkeit formatiert.
curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/conversations
    ?platform=PLATFORM
    &access_token=PAGE-ACCESS-TOKEN"

Wenn der Vorgang erfolgreich verläuft, erhält deine App ein JSON-Objekt mit einer Liste von IDs für die Unterhaltungen zwischen dir und einer Person und dem letzten Zeitpunkt, zu dem eine Nachricht gesendet wurde.

{
  "data": 
    {
      "id": "CONVERSATION-ID-1",  
      "updated_time": "UNIX-TIMESTAMP"
    },
    {
      "id": "CONVERSATION-ID-2",   
      "updated_time": "UNIX-TIMESTAMP"
    }
    ...
  ]
}

Eine Unterhaltung mit einem*einer bestimmten Nutzer*in finden

Um eine Unterhaltung zwischen deinem professionellen Instagram-Konto oder deiner Facebook-Seite und einer bestimmten Person abzurufen, sende eine GET-Anfrage an den /PAGE-ID/conversations-Endpunkt, wobei die Parameter platform und user_id auf die Instagram-spezifische ID oder die seitenspezifische ID für die Person festgelegt sind.

Beispielanfrage

Für Lesbarkeit formatiert.
curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/conversations
    ?platform=PLATFORM
    &user_id=INSTAGRAM-OR-PAGE-SCOPED-ID
    &access_token=PAGE-ACCESS-TOKEN"

Wenn der Vorgang erfolgreich verläuft, hält deine App die ID für die Unterhaltung.


{
  "data": [
      {
        "id": "CONVERSATION-ID"
      },
  ]
}

Eine Liste mit Nachrichten in einer Unterhaltung abrufen

Um eine Liste mit Nachrichten in einer Unterhaltung abzurufen, sende eine GET-Anfrage an den /CONVERSATION-ID-Endpunkt und schließe das Feld messages ein.

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/CONVERSATION-ID
    ?fields=messages
    &access_token=PAGE-ACCESS-TOKEN"

Wenn der Vorgang erfolgreich verläuft, erhält deine App eine Liste mit Nachrichten-IDs und dem Zeitpunkt, zu dem jede Nachricht erstellt wurde.

{
  "messages": {
    "data": [
      {
        "id": "Message ID-1",      
        "created_time": "UNIX-TIMESTAMP-MOST-RECENT-MESSAGE"  
      },
      {
        "id": "Message ID-2",
        "created_time": "UNIX-TIMESTAMP"
      },
      {
        "id": "Message ID-3",
        "created_time": "UNIX-TIMESTAMP"
      },
...
    ]
  },
  "id": "Conversation ID", 
}

Informationen über eine Nachricht abrufen

Um Informationen über eine Nachricht abzurufen, wie z. B. den*die Absender*in, den*die Empfänger*in und den Inhalt der Nachricht, sende eine GET-Anfrage an den /MESSAGE-ID-Endpunkt mit den Feldern, die dich interessieren.

Standardfelder sind id und created_time.

Hinweis: Abfragen an den /CONVERSATION-ID-Endpunkt geben alle Nachrichten-IDs in einer Unterhaltung zurück. Du kannst allerdings nur Details zu den 20 letzten Nachrichten in der Unterhaltung abrufen. Wenn du eine Nachricht abfragst, die älter als die letzten 20 ist, wird dir der Fehler angezeigt, dass die Nachricht gelöscht wurde. 

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/MESSAGE-ID
    ?fields=id,created_time,from,to,message
    &access_token=PAGE-ACCESS-TOKEN"

Wenn der Vorgang erfolgreich verläuft, erhält deine App die folgende JSON-Antwort. In diesem Beispiel hat ein*e Kund*in eine einfache Textnachricht an dein professionelles Instagram-Konto geschickt.

{
  "id": "aWdGGiblWZ...",
  "created_time": "2022-07-12T19:11:07+0000",
  "to": {
    "data": [
      {
        "username": "INSTAGRAM-PROFESSIONAL-ACCOUNT-USERNAME",
        "id": "INSTAGRAM-PROFESSIONAL-ACCOUNT-ID"
      }
    ]
  },
  "from": {
    "username": "INSTAGRAM-USERNAME",
    "id": "INSTAGRAM-SCOPED-ID"
  },
  "message": "Hi Kitty!"
}

Mehr dazu

Unsere Referenzen für:

Unterstützung für Entwickler*innen