Schnellstart-Tutorial

Sofern nicht bereits erledigt, befolge die Anweisungen im Leitfaden zur App-Einrichtung, um deine Facebook-App für die Nutzung der Messenger-Plattform einzurichten.

Alle Anfragen an die Messenger Platform APIs werden durch einen Seitenzugriffsschlüssel authentifiziert, der im access_token-Parameter des Abfrage-Strings enthalten ist.

Wenn du das nicht schon beim Einrichten deiner Facebook-App gemacht hast, erstelle einen Seiten-Zugriffsschlüssel mit folgenden Schritten:

Wir empfehlen dir, vertrauliche Informationen wie deinen Seiten-Zugriffsschlüssel zu schützen, indem du sie nicht in deinen Webhook hartcodierst.

Füge dazu Folgendes zu deinen Umgebungsvariablen hinzu. Dabei ist <PAGE_ACCESS_TOKEN> der gerade generierte Zugriffsschlüssel und <VERIFY_TOKEN> ist ein zufälliger String, den du zur Verifizierung deines Webhooks einstellst:

PAGE_ACCESS_TOKEN="

Jetzt musst du nur noch deinen Seiten-Zugriffsschlüssel und Bestätigungsschlüssel oben in deiner app.js-Datei einfügen, damit du sie in deiner Webhook-Logik verwenden kannst:

const PAGE_ACCESS_TOKEN = process.env.PAGE_ACCESS_TOKEN;
const VERIFY_TOKEN = process.env.VERIFY_TOKEN;

Zunächst erstellen wir Stubs für drei Funktionen, die die eingehenden Webhook-Event-Arten verarbeiten, die unterstützt werden sollen, sowie Antworten über die Send API. Hierzu hängen wir Folgendes an die app.js-Datei an:

// Handles messages events
function handleMessage(sender_psid, received_message) {

}

// Handles messaging_postbacks events
function handlePostback(sender_psid, received_postback) {

}

// Sends response messages via the Send API
function callSendAPI(sender_psid, response) {
  
}

Um Nachrichten von Personen im Messenger zu beantworten, müssen wir zuerst wissen, wer die Absender*innen sind. In Messenger erreichst du das, indem du die seitenspezifische ID (PSID) des*der Absender*in aus dem eingehenden Webhook-Event abrufst.

Was ist eine PSID?

Einer Person wird für jede Facebook-Seite, mit der sie eine Unterhaltung beginnt, eine individuelle seitenspezifische ID (PSID) zugewiesen. Anhand dieser PSID wird der Absender einer Nachricht identifiziert.

Wenn du eine der Optionen im Abschnitt Starterprojekt weiter oben abgeschlossen hast, solltest du über einen einfachen /webhook-Endpunkt verfügen, der POST-Anfragen akzeptiert und den Hauptteil von empfangenen Webhook-Events protokolliert (sieht wie folgt aus):

app.post('/webhook', (req, res) => {  

  // Parse the request body from the POST
  let body = req.body;

  // Check the webhook event is from a Page subscription
  if (body.object === 'page') {

    // Iterate over each entry - there may be multiple if batched
    body.entry.forEach(function(entry) {

      // Get the webhook event. entry.messaging is an array, but 
      // will only ever contain one event, so we get index 0
      let webhook_event = entry.messaging[0];
      console.log(webhook_event);
      
    });

    // Return a '200 OK' response to all events
    res.status(200).send('EVENT_RECEIVED');

  } else {
    // Return a '404 Not Found' if event is not from a page subscription
    res.sendStatus(404);
  }

});

Um die PSID des Absenders abzurufen, aktualisiere den body.entry.forEach-Block mit dem folgenden Code, um die PSID aus der sender.id-Eigenschaft des Events zu extrahieren:

Unser Messenger-Erlebnis soll zwei Arten von Webhook-Events verarbeiten: messages und messaging_postback. Der Name der Event-Art ist nicht im Event-Hauptteil enthalten. Wir können ihn aber durch eine Prüfung auf bestimmte Objekteigenschaften ermitteln.

Was sind Webhook-Events?

Die Messenger-Plattform versendet Webhook-Events, um dich über Handlungen im Messenger zu informieren. Events werden im JSON-Format als POST-Anfragen an deinen Webhook gesendet. Weitere Informationen findest du unter Webhook-Events.

Aktualisiere hierzu du den body.entry.forEach-Block deines Webhooks mit einer Bedingung, die prüft, ob das empfangene Event eine message- oder postback-Eigenschaft enthält. Außerdem fügen wir Aufrufe zu den handleMessage()- und handlePostback()-Funktionen hinzu, für die wir zuvor Stubs erstellt haben:

body.entry.forEach(function(entry) {

  // Gets the body of the webhook event
  let webhook_event = entry.messaging[0];
  console.log(webhook_event);


  // Get the sender PSID
  let sender_psid = webhook_event.sender.id;
  console.log('Sender PSID: ' + sender_psid);

  // Check if the event is a message or postback and
  // pass the event to the appropriate handler function
  if (webhook_event.message) {
    handleMessage(sender_psid, webhook_event.message);        
  } else if (webhook_event.postback) {
    handlePostback(sender_psid, webhook_event.postback);
  }
  
});

Jetzt, da die eingehenden Nachrichten an die jeweilige Handler-Funktion weitergeleitet werden, aktualisierst du handleMessage(), damit einfache Textnachrichten verarbeitet und beantwortet werden. Aktualisiere dazu den Code, um die Nachrichten-Payload der Antwort zu definieren, und übergib diese Payload dann an callSendAPI(). Definiere ein JSON-Objekt mit einer "text"-Eigenschaft, um eine einfache Textnachricht als Antwort zu senden:

function handleMessage(sender_psid, received_message) {

  let response;

  // Check if the message contains text
  if (received_message.text) {    

    // Create the payload for a basic text message
    response = {
      "text": `You sent the message: "${received_message.text}". Now send me an image!`
    }
  }  
  
  // Sends the response message
  callSendAPI(sender_psid, response);    
}

Jetzt ist es an der Zeit, deine erste Nachricht mit der Send API der Messenger-Plattform zu senden.

In handleMessage() rufst du callSendAPI() auf. Dieses muss jetzt aktualisiert werden, um den vollständigen Anfragehauptteil zu erstellen und an die Messenger-Plattform zu senden. Eine Anfrage an die Send API hat zwei Eigenschaften:

• recipient: Legt den Empfänger der Nachricht fest. In diesem Fall wird die Person anhand ihrer PSID identifiziert.
• message: Legt Details zur Nachricht fest, die gesendet werden soll. Hier legen wir das auf das Nachrichtenobjekt fest, das du aus der handleMessage()-Funktion übergeben hast.

Um den Anfragehauptteil zu erstellen, aktualisiere den Stub für callSendAPI() auf Folgendes:

function callSendAPI(sender_psid, response) {
  // Construct the message body
  let request_body = {
    "recipient": {
      "id": sender_psid
    },
    "message": response
  }
}

Jetzt musst du nur noch deine Nachricht senden, indem du eine POST-Anfrage an die Send API unter https://graph.facebook.com/v2.6/me/messages sendest.

Beachte, dass du deinen PAGE_ACCESS_TOKEN im access_token-Parameter des URL-Abfrage-Strings anhängen musst.

const request = require('request');

function callSendAPI(sender_psid, response) {
  // Construct the message body
  let request_body = {
    "recipient": {
      "id": sender_psid
    },
    "message": response
  }

  // Send the HTTP request to the Messenger Platform
  request({
    "uri": "https://graph.facebook.com/v2.6/me/messages",
    "qs": { "access_token": process.env.PAGE_ACCESS_TOKEN },
    "method": "POST",
    "json": request_body
  }, (err, res, body) => {
    if (!err) {
      console.log('message sent!')
    } else {
      console.error("Unable to send message:" + err);
    }
  }); 
}

Teste das Setup.

Sende im Messenger eine weitere Textnachricht an deine Facebook-Seite. Du solltest eine automatische Antwort von deinem Messenger-Erlebnis erhalten, die deine Nachricht wiederholt und dich auffordert, ein Bild zu senden.

Da wir den Nachrichtenempfänger in unserer Antwort dazu aufgefordert haben, ein Bild zu senden, müssen wir als Nächstes unseren Code ändern, damit wir Anhänge verarbeiten können. Gesendete Anhänge werden automatisch von der Messenger-Plattform gespeichert und über eine URL in der payload.url-Eigenschaft von jedem Index im attachments-Array verfügbar gemacht. Wir extrahieren das also auch aus dem Event.

Welche Anhangsarten werden unterstützt?

Dein Messenger-Erlebnis kann die meisten Medientypen senden und empfangen, darunter Bilder, Audio, Video und Dateien. Medien werden angezeigt und können sogar in der Unterhaltung wiedergegeben werden, sodass du Rich-Media-Erlebnisse erstellen kannst.

Um zu ermitteln, ob es sich bei der Nachricht um einen Anhang handelt, aktualisiere die Bedingung in deiner handleMessage()-Funktion, um die received_message auf eine attachments-Eigenschaft zu prüfen, und extrahiere dann die URL dafür. Bei einem echten Bot würden wir das Array wiederholen, um zu prüfen, ob es mehrere Anhänge gibt. Für diesen Schnellstart rufen wir aber nur den ersten Anhang ab.

function handleMessage(sender_psid, received_message) {

  let response;

  // Checks if the message contains text
  if (received_message.text) {
    
    // Creates the payload for a basic text message, which
    // will be added to the body of our request to the Send API
    response = {
      "text": `You sent the message: "${received_message.text}". Now send me an attachment!`
    }

  } else if (received_message.attachments) {
  
    // Gets the URL of the message attachment
    let attachment_url = received_message.attachments[0].payload.url;
  
  } 
  
  // Sends the response message
  callSendAPI(sender_psid, response);    
}

Als Nächstes senden wir eine Nachricht mit der generischen Vorlage als Antwort auf das Bild. Die generische Vorlage ist die am häufigsten verwendete Art von strukturierten Nachrichten. Damit kannst du ein Bild, Text und Buttons in einer Nachricht senden.

Gibt es noch weitere Nachrichtenvorlagen?

Ja. Die Messenger-Plattform bietet eine Reihe nützlicher Nachrichtenvorlagen, von denen jede eine andere gängige Nachrichtenstruktur unterstützt, darunter Listen, Zahlungsbelege, Buttons und mehr. Alle Details dazu findest du unter Vorlagen.

Nachrichtenvorlagen werden in der attachment-Eigenschaft der Nachricht definiert, die type- und payload-Eigenschaften enthält. In der payload legen wir die Details zu unserer generischen Vorlage in den folgenden Eigenschaften fest:

• template_type: Legt die Art der verwendeten Vorlage für die Nachricht fest. Wir verwenden hier die generische Vorlage. Der Wert lautet also „generic“.
• elements: Legt die benutzerdefinierten Eigenschaften der Vorlage fest. Für die generische Vorlage geben wir einen Titel, einen Untertitel, ein Bild und zwei Postback-Buttons an.

Für die strukturierte Nachricht verwenden wir die attachment_url, die uns als image_url gesendet wurde, in unserer Vorlage und fügen einige Postback-Buttons hinzu, damit der Nachrichtenempfänger antworten kann. Um die Nachrichten-Payload zu erstellen und die generische Vorlage zu senden, legen wir für handleMessage() Folgendes fest:

Als letzten Schritt verarbeiten wir das messaging_postbacks-Webhook-Event, das gesendet wird, wenn der*die Nachrichtenempfänger*in auf einen der Postback-Buttons in der generischen Vorlage tippt.

Was kann ich mit Postbacks machen?

Der Postback-Button sendet ein messaging_postbacks-Webhook-Event an deinen Webhook, das einen benutzerdefinierten String mit bis zu 1.000 Zeichen in der payload-Eigenschaft enthält. So kannst du einfach verschiedene Postback-Payloads implementieren, die du parsen und auf die du mit bestimmten Handlungen reagieren kannst.

Da unsere generische Vorlage dem*der Nachrichtenempfänger*in die Auswahl zwischen zwei Postback-Buttons bietet, antworten wir basierend auf dem Wert der payload-Eigenschaft des Postback-Events. Stelle dazu deinen handlePostback()-Stub auf Folgendes ein: