Webhooks für die Messenger-Plattform

Mit 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 ein*e Kund*in deinem Unternehmen eine Nachricht sendet. Mit Webhooks-Benachrichtigungen kannst du Messaging-Änderungen nachverfolgen und Ratenbegrenzungen vermeiden, die auftreten können, wenn du die Endpunkte der Messenger-Plattform abfragst, um Änderungen nachzuverfolgen.

Führe folgende Schritte aus, um Webhooks für die Messenger-Plattform – 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:

• Die Übersicht über die Messenger-Plattform gelesen und die zur Entwicklung mit Meta erforderlichen Komponenten implementiert haben

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 gezeigten 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 Bestätigungsschlüssel festgelegt hast (du hast diesen Schlüssel-String noch nicht festgelegt).
• Senden einer 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 in Parameternamen Punkte (.) 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 einer deiner App-Nutzer 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.

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.

Teste deine Webhooks

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.

Konfiguration des Webhooks-Produkts

Wenn dein Endpunkt oder deine Beispiel-App bereit ist, füge mithilfe des App-Dashboards deiner App den Nachrichten-Webhook zum Messenger-Produkt hinzu und konfiguriere ihn. Navigiere zu Messenger > Einstellungen, um Webhooks für Messenger zu abonnieren. Navigiere zu Messenger > Instagram-Einstellungen, um Webhooks für Instagram Messaging zu abonnieren. Du kannst dies mit dem /app/subscriptions-Endpunkt programmgesteuert durchführen.

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.

2. Gib die URL deines Endpunkts im Feld Callback-URL ein füge dein Verifizierungstoken im Feld Verifizierungstoken hinzu. 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. Scrolle nach unten zu Webhooks und suche die Seite, die mit deinem professionellen Instagram-Konto verknüpft ist, und klicke dann auf den Button Abonnement hinzufügen.
4. Abonniere Felder, für die du Benachrichtigungen erhalten möchtest, und klicke auf Speichern.

5. 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.

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

Du kannst eine App unter Meta Business Suite > Alle Tools > Business-Appsmit 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-Zugriffsschlüssel, der von einer Person angefordert wurde, die die MODERATE-Aufgabe auf der angeforderten Seite ausführen kann
• Die pages_messaging- und pages_manage_metadata-Berechtigungen

Um ein Webhooks-Feld zu abonnieren, sendest du mithilfe des Zugriffsschlüssels 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-Zugriffsschlüssel abrufen und anschließend die Berechtigung pages_manage_metadata aus. Dadurch wird dein App-Schlüssel gegen einen Nutzer-Zugriffsschlüssel mit der pages_manage_metadata-Berechtigung getauscht.
3. Klicke erneut auf Token anfordern und wähle deine Seite aus. Dadurch wird dein Nutzer-Zugriffsschlüssel durch einen Seiten-Zugriffsschlüssel 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, 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

Sieh dir unsere Beispiel-App an – 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