Meta-Webhooks für die Messenger-Plattform

Mit Meta-Webhooks erhältst du HTTP-Benachrichtigungen in Echtzeit, die dich über Änderungen an bestimmten Objekten im Meta Social Graph informieren. Wir können dir beispielsweise eine Benachrichtigung senden, wenn eine Person deiner Facebook-Seite oder deinem professionellen Instagram-Konto eine Nachricht sendet. Anhand von Webhooks-Benachrichtigungen kannst du eingehende Nachrichten und Status-Updates zu Nachrichten nachverfolgen. Mit Webhooks-Benachrichtigungen kannst du außerdem Durchsatzratenbegrenzungen vermeiden, die auftreten können, wenn du die Endpunkte der Messenger-Plattform abfragst, um diese Änderungen nachzuverfolgen.

Führe folgende Schritte aus, um Webhooks für Messenger- oder Instagram-Unterhaltungen erfolgreich zu implementieren:

1. Erstelle einen Endpunkt auf deinem Server, um deine Webhooks-Benachrichtigungen zu erhalten und als JSON-Objekte zu verarbeiten.
2. Konfiguriere das Meta-Webhooks-Produkt in deinem App-Dashboard.
3. Abonniere die Meta-Webhooks-Benachrichtigungen, die du erhalten möchtest.
4. Installiere deine Massaging-App auf der Facebook-Seite, die mit deinem Unternehmen oder deinem professionellen Instagram-Konto verknüpft ist.

Bevor du beginnst

Bevor du beginnst, solltest du folgende Schritte erledigt haben:

• Die Informationen zu den für die Entwicklung mit Meta erforderlichen Komponenten in der Messenger-Plattformübersicht lesen und implementieren.

Deinen Node.js-Server konfigurieren

Dein Server muss zwei Arten von HTTPS-Anfragen verarbeiten können: Verifizierungsanfragen und Event-Benachrichtigungen. Da beide Anfragen HTTPS verwenden, muss dein Server über ein korrekt konfiguriertes und installiertes TLS- oder SSL-Zertifikat verfügen. Selbstsignierte Zertifikate werden nicht unterstützt.

In den Abschnitten unten wird erläutert, was die einzelnen Anfragetypen enthalten und wie darauf zu reagieren ist.

Die hier angezeigten Codebeispiele stammen aus unserer Beispiel-App auf GitHub. Rufe GitHub auf, um das vollständige Beispiel zu sehen und mehr über die Einrichtung deines Webhooks-Servers zu erfahren.

Endpunkt erstellen

Die zum Erstellen eines Endpunkts für den Empfang von Webhooks-Benachrichtigungen von der Messenger-Plattform verwendete app.js-Datei kann etwa so aussehen:

// Create the endpoint for your webhook

app.post("/webhook", (req, res) => {
  let body = req.body;

  console.log(`\u{1F7EA} Received webhook:`);
  console.dir(body, { depth: null });
    
...
   

Dieser Code erstellt einen /webhook-Endpunkt, der POST-Anfragen akzeptiert und überprüft, ob es sich bei der Anfrage um eine Webhooks-Benachrichtigung handelt.

Eine 200 OK-Antwort zurückgeben

Der Endpunkt muss eine 200 OK-Antwort zurückgeben, die der Messenger-Plattform mitteilt, dass das Event empfangen wurde und nicht erneut gesendet werden muss. In der Regel wird diese Antwort nicht gesendet, bis du die Benachrichtigung erfolgreich verarbeitet hast.

Antworten auf Event-Benachrichtigungen

Dein Endpunkt sollte folgendermaßen auf alle Benachrichtigungen antworten:

• mit einer 200 OK HTTPS-Antwort
• innerhalb von fünf Sekunden

Der folgende Code wird sich im app.post in deiner app.js-Datei befinden und kann etwa so aussehen:

...
  // Send a 200 OK response if this is a page webhook

  if (body.object === "page") {
    // Returns a '200 OK' response to all requests
    res.status(200).send("EVENT_RECEIVED");
...
    // Determine which webhooks were triggered and get sender PSIDs and locale, message content and more.
...
  } else {
    // Return a '404 Not Found' if event is not from a page subscription
    res.sendStatus(404);
  }
}); 

Verifizierungsanfragen

Jedes Mal, wenn du das Webhooks-Produkt im App-Dashboard konfigurierst, senden wir eine GET-Anfrage an deine Endpunkt-URL. Verifizierungsanfragen enthalten die folgenden Abfrage-String-Parameter, die an das Ende deiner Endpunkt-URL angehängt werden. Sie sehen in etwa wie folgt aus:

Beispiel-Verifizierungsanfrage

GET https://www.your-clever-domain-name.com/webhooks? hub.mode=subscribe& hub.verify_token=mytoken& hub.challenge=1158201444

Validierung von Verifizierungsanfragen

Jedes Mal, wenn dein Endpunkt eine Verifizierungsanfrage erhält, muss er folgende Schritte ausführen:

• Verifizieren, dass der hub.verify_token-Wert mit dem String übereinstimmt, den du bei der Konfiguration des Webhooks-Produkts in deinem App-Dashboard im Feld Verifizierungstoken festgelegt hast (du hast diesen Token-String noch nicht festgelegt).
• Sende eine Antwort mit dem hub.challenge-Wert.

Deine app.js-Datei könnte wie folgt aussehen:

// Add support for GET requests to our webhook
app.get("/messaging-webhook", (req, res) => {
  
// Parse the query params
  let mode = req.query["hub.mode"];
  let token = req.query["hub.verify_token"];
  let challenge = req.query["hub.challenge"];

  // Check if a token and mode is in the query string of the request
  if (mode && token) {
    // Check the mode and token sent is correct
    if (mode === "subscribe" && token === config.verifyToken) {
      // Respond with the challenge token from the request
      console.log("WEBHOOK_VERIFIED");
      res.status(200).send(challenge);
    } else {
      // Respond with '403 Forbidden' if verify tokens do not match
      res.sendStatus(403);
    }
  }
});

Hinweis:PHP konvertiert Punkte (.) in Parameternamen in Unterstriche (_).

Wenn du dein App-Dashboard aufgerufen hast und dein Webhooks-Produkt konfigurierst (und somit eine Verifizierungsanfrage auslöst), wird im Dashboard angezeigt, ob dein Endpunkt die Anfrage richtig validiert hat. Wenn du zur Konfiguration des Webhooks-Produkts den /app/subscriptions-Endpunkt der Graph API verwendest, sendet die API eine Antwort mit einer Erfolgs- oder Fehlerangabe.

Event-Benachrichtigungen

Wenn du dein Webhooks-Produkt konfigurierst, abonnierst du bestimmte fields für einen object-Typ (z. B. das messages-Feld für das page-Objekt). Wird eines dieser Felder geändert, senden wir eine POST-Anfrage mit einer JSON-Payload an deinen Endpunkt, die die Änderung beschreibt.

Hast du beispielsweise das message_reactions-Feld des page-Objekts abonniert und eine*r deine*r App-Nutzer*innen reagiert auf eine von deiner App gesendeten Nachricht, senden wir dir eine POST-Anfrage ähnlich der Folgenden:

{
  "object":"page",
  "entry":[
    {
      "id":"<PAGE_ID>",
      "time":1458692752478,
      "messaging":[
        {
          "sender":{
            "id":"<PSID>"
          },
          "recipient":{
            "id":"<PAGE_ID>"
          },

          ...
        }
      ]
    }
  ]
}

Payload-Inhalt

Payloads enthalten ein Objekt mit einer Beschreibung der Änderung. Wenn du das Webhooks-Produkt konfigurierst, kannst du angeben, ob Payloads nur die Namen der geänderten Felder oder auch die neuen Werte enthalten sollen.

Wir formatieren alle Payloads mit JSON, damit du die Payload mit den gängigen JSON-Parsing-Methoden oder Paketen parsen kannst.

Hinweis: Wir können keine historischen Webhook-Event-Benachrichtigungsdaten abfragen. Stelle also sicher, dass du den gesamten Webhook-Payload-Inhalt, den du beibehalten möchtest, erfasst und speicherst.

Validierung von Payloads

Wir signieren alle Event-Benachrichtigungs-Payloads mit einer SHA256-Signatur und beziehen die Signatur in den Header „X-Hub-Signature-256“ der Anfrage ein, dem „sha256=" vorangestellt wird. Du musst die Payload nicht validieren, jedoch solltest du dies tun und es wird dringend empfohlen.

So validierst du die Payload:

1. Generiere eine SHA256-Signatur mit der Payload und dem App-Geheimcode deiner App.
2. Vergleiche deine Signatur mit der Signatur im X-Hub-Signature-256-Header (alles nach sha256=). Stimmen die Signaturen überein, ist die Payload echt.

Die app.js-Datei könnte wie folgt aussehen:

// Import dependencies and set up http server
const express = require("express"),
  bodyParser = require("body-parser"),
  { urlencoded, json } = require("body-parser"),
  app = express().use(bodyParser.json());
    
    ...


// Verify that the callback came from Facebook.
function verifyRequestSignature(req, res, buf) {
  var signature = req.headers["x-hub-signature-256"];

  if (!signature) {
    console.warn(`Couldn't find "x-hub-signature-256" in headers.`);
  } else {
    var elements = signature.split("=");
    var signatureHash = elements[1];
    var expectedHash = crypto
      .createHmac("sha256", config.appSecret)
      .update(buf)
      .digest("hex");
    if (signatureHash != expectedHash) {
      throw new Error("Couldn't validate the request signature.");
    }
  }
}

Wiederholung der Webhooks-Zustellung

Wenn das Senden einer Benachrichtigung an deinen Server fehlschlägt, erfolgen sofort neue Versuche. Dein Server sollte die Deduplizierung in diesen Fällen verarbeiten können. Wenn es nach 15 Minuten weiterhin nicht möglich ist, Benachrichtigungen zuzustellen, wird eine Warnung an dein Entwicklerkonto gesendet.

Wenn die Zustellung einer Benachrichtigung weiterhin eine Stunde lang fehlschlägt, erhältst du den Warnhinweis Webhooks deaktiviert und das Abonnement deiner App für den Webhook der Seite oder des professionellen Instagram-Kontos wird eingestellt. Sobald du die Probleme behoben hast, musst du die Webhooks erneut abonnieren.

Webhooks testen

Um deine Webhook-Verifizierung zu testen, führe die folgende cURL-Anfrage mit deinem Verifizierungstoken durch:

curl -X GET "localhost:1337/webhook?hub.verify_token=YOUR-VERIFY-TOKEN&hub.challenge=CHALLENGE_ACCEPTED&hub.mode=subscribe"

Wenn die Webhook-Verifizierung wie erwartet funktioniert, sollte Folgendes angezeigt werden:

• WEBHOOK_VERIFIED in der Befehlszeile, in der dein Node-Prozess ausgeführt wird.
• CHALLENGE_ACCEPTED in der Befehlszeile, in der du die cURL-Anfrage gesendet hast.

Teste deinen Webhook, indem du folgende cURL-Anfrage sendest:

curl -H "Content-Type: application/json" -X POST "localhost:1337/webhook" -d '{"object": "page", "entry": [{"messaging": [{"message": "TEST_MESSAGE"}]}]}'

Wenn dein Webhook wie erwartet funktioniert, sollte Folgendes angezeigt werden:

• TEST_MESSAGE in der Befehlszeile, in der dein Node-Prozess ausgeführt wird.
• EVENT RECEIVED in der Befehlszeile, in der du die cURL-Anfrage gesendet hast.

Meta-Webhooks abonnieren

Wenn der Server-Endpunkt deiner Webhooks oder deine Beispiel-App bereit ist, navigiere in deiner App zum App-Dashboard von Meta, um Meta-Webhooks zu abonnieren.

In diesem Beispiel verwenden wir das Dashboard, um einen Webhook zu konfigurieren und das messages-Feld zu abonnieren. Jedes Mal, wenn ein*e Kund*in deiner App eine Nachricht sendet, wird eine Benachrichtigung an deinen Webhooks-Endpunkt gesendet.

1. Gehe im App-Dashboard zu Produkte > Messenger > Einstellungen.
   • Manche Messenger-Plattform-Webhooks sind nicht für Instagram-Messaging verfügbar. Wenn du Webhooks nur für Instagram implementierst und die für Instagram-Messaging verfügbaren Webhooks kennst, kannst du hier Webhooks abonnieren. Möchtest du nur die Webhooks für das Messaging auf Instagram ansehen und abonnieren, dann kannst du auch die Einstellungen für Instagram aufrufen.
2. Gib im Feld Rückruf-URL die URL deines Endpunkts und im Feld Verifizierungstoken dein Verifizierungstoken ein. Der String wird zu allen Verifizierungsanfragen hinzugefügt. Wenn du eine unserer Beispiel-Apps verwendest, sollte es derselbe String sein, den du für die TOKEN-Konfigurationsvariable deiner App verwendet hast.
3. Abonniere die Felder, zu denen du Benachrichtigungen erhalten möchtest, und klicke dann auf Speichern.
4. Der letzte Schritt ist das Abonnement einzelner Felder. Abonniere das messages-Feld und sende eine Test-Event-Benachrichtigung.
   • Ist dein Endpunkt richtig eingerichtet, sollte er die Payload validieren und den Code ausführen, den du bei erfolgreicher Validierung festgelegt hast. Wenn du unsere Beispiel-App nutzt, lade die URL der App in deinen Web-Browser. Der Inhalt der Payload sollte angezeigt werden.

Du kannst deine Webhooks-Abonnements, das Verifizierungstoken oder die API-Version jederzeit über das App-Dashboard ändern.

Hinweis: Um alle verfügbaren Informationen zu jedem Webhook zu erhalten, solltest du unbedingt die neueste API-Version verwenden.

Du kannst dies mit dem /app/subscriptions-Endpunkt auch programmgesteuert durchführen.

Verfügbare Felder auf der Messenger-Plattform

Verbinden der App

Du musst deine Webhooks-App mit deiner Seite verbinden und deine Seite für die Webhooks-Benachrichtigungen abonnieren, die du erhalten möchtest.

Hinzufügen der App

Unter Meta Business Suite > Alle Tools > Business-Apps kannst du eine App mit einer Seite verbinden.

Hinweis: Du musst alle Messaging-Apps für dein Unternehmen im Messaging-Webhook abonnieren.

Abonnieren der Seite

Du musst deine Seite für die Webhooks-Benachrichtigungen abonnieren, die du erhalten möchtest.

Anforderungen

• Ein Seiten-Zugriffstoken, das von einer Person angefordert wurde, die die MODERATE-Aufgabe auf der angeforderten Seite ausführen kann
• Die Berechtigungen pages_messaging und pages_manage_metadata

Um ein Webhooks-Feld zu abonnieren, sendest du mithilfe des Zugriffstokens der Seite eine POST-Anfrage an die subscribed_apps-Edge der Seite.

curl -i -X POST "https://graph.facebook.com/PAGE-ID/subscribed_apps
  ?subscribed_fields=messages
  &access_token=PAGE-ACCESS-TOKEN"

Beispielantwort

{
  "success": "true"
}

Wenn du ermitteln möchtest, welche Apps für deine Seite installiert sind, sende stattdessen eine GET-Anfrage:

Beispielanfrage

curl -i -X GET "https://graph.facebook.com/PAGE-ID/subscribed_apps
  &access_token=PAGE-ACCESS-TOKEN"

Beispielantwort

{
  "data": [
    {
      "category": "Business",
      "link": "https://my-clever-domain-name.com/app",
      "name": "My Sample App",
      "id": "APP-ID"
      "subscribed_fields": [
        "messages"
      ]
    }
  ]
}

Wenn für deine Seite keine Apps installiert sind, gibt die API einen leeren Datensatz zurück.

Graph API Explorer

Du kannst auch den Graph API Explorer verwenden, um die Abonnementanfrage deiner Seite für ein Webhook-Feld zu senden.

1. Wähle deine App im Dropdown-Menü Anwendung aus.
2. Klicke auf das Dropdown-Menü Token anfordern und wähle Nutzer-Zugriffstoken abrufen und anschließend die Berechtigung pages_manage_metadata aus. Dadurch wird dein App-Token gegen ein Nutzer-Zugriffstoken mit der pages_manage_metadata-Berechtigung getauscht.
3. Klicke erneut auf Token anfordern und wähle deine Seite aus. Dadurch wird dein Nutzer-Zugriffstoken durch ein Seiten-Zugriffstoken ersetzt.
4. Ändere die Vorgangsmethode, indem du auf das Dropdown-Menü GET klickst und POST auswählst.
5. Ersetze die Standardanfrage me?fields=id,name durch die ID der Seite gefolgt von /subscribed_apps und übermittle die Anfrage dann.

Zugriffsanforderungen

Um Benachrichtigungen von Personen zu erhalten, die eine Rolle in deiner App innehaben, z. B. Admins, Entwickler*innen oder Tester*innen, benötigt deine App lediglich Standardzugriff. Damit du Nachrichten von deinen Kund*innen, also Personen, die keine Rolle in deiner App innehaben, erhalten kannst, benötigt deine App erweiterten Zugriff.

Weitere Informationen zu Standardzugriff und erweitertem Zugriff, den jeweils zugänglichen Daten und den Anforderungen für die Implementierung.

Nächste Schritte

• Eine Testnachricht senden – Erfahre wie, du mithilfe der Plattform eine Nachricht senden kannst.
• Unsere Beispiel-App ansehen – Lade Code für unsere Beispiel-App herunter, um mehr über die Funktionen der Messenger-Plattform zu erfahren.

Siehe auch

• Erfahre, wie du Benachrichtigungen erhältst, wenn eine Unterhaltung mithilfe des Messenger-Übergabeprotokolls von einer App an eine andere übergeben wird.
• Erfahre mehr über Meta Webhooks für Graph API