Einmalige Benachrichtigung (Beta)

Zusammenfassung

Mit der One-Time Notification API (Beta) der Messenger-Plattform kann eine Seite eine*n Nutzer*in auffordern, eine Follow-up-Nachricht zu senden, nachdem das 24-Stunden-Messaging-Fenster abgelaufen ist. Dem*der Nutzer*in wird angeboten, künftig eine Benachrichtigung zu erhalten. Sobald der*die Nutzer*in darum bittet, benachrichtigt zu werden, erhält die Seite einen Schlüssel, der einer Erlaubnis entspricht, dem*der Nutzer*in eine einzelne Nachricht zu senden. Der Token kann nur einmal verwendet werden und verfällt innerhalb eines Jahres nach Erstellung.

Berechtigungen

Seiten, die diese API verwenden möchten, müssen im Abschnitt „Erweitertes Messaging“ der Seiteneinstellungen die Berechtigung „Einmalige Benachrichtigung“ beantragen. Die Seite muss den Beta-Bedingungen zustimmen und erhält dann die Berechtigung, sofern sie unsere Kriterien erfüllt.

Inhalt

• Verwendung
• Senden einer Anfrage für einmalige Benachrichtigungen
• Senden einer Follow-up-Nachricht
• Webhook-Events
• Begrenzungen und Einschränkungen

Verwendung

• Du darfst Nutzer*innen nicht verwirren, täuschen, betrügen, irreführen, ihnen Spam senden oder sie unangenehm überraschen. Stelle sicher, dass zwischen der Anfrage und dem Inhalt der Nachricht eine klare und offensichtliche Beziehung besteht. Der Inhalt der Anfrage für einmalige Benachrichtigungen und die eigentliche Nachricht müssen die Gemeinschaftsstandards erfüllen.
• Seiten, die viel negatives Feedback von Nutzer*innen erhalten haben oder die Nutzer*innen verwirren, täuschen, betrügen, in die Irre führen bzw. sie unangenehm überraschen, wird der Zugriff auf die API entzogen.

Senden einer Anfrage für einmalige Benachrichtigungen

Mithilfe der Send API kann die Seite eine Nachricht zur Benachrichtigungsanfrage als Vorlage senden. Der Vorlagentyp sollte folgendermaßen lauten: one_time_notif_req. Der Hauptteil der Anfrage folgt einem Standardformat für alle Vorlagentypen, wobei die message.attachment.payload-Eigenschaft die Typ- und Inhaltsdetails enthält, die für den jeweiligen Vorlagentyp spezifisch sind. Du darfst nur den Titel und die Payload der Anfrage anpassen. Das Feld title ist auf 65 Zeichen beschränkt.

{
  "recipient": {
    "id":"

Die Anfragenvorlage für einmalige Benachrichtigungen wird gerendert und sobald der*die Nutzer*in auf den Button „Mich benachrichtigen“ klickt, wird an dein Backend ein message_optins-Webhook gesendet. Dann kann über das one_time_notif_token außerhalb des 24-Stunden-Zeitraums an den*die Nutzer*in eine einmalige Follow-up-Nachricht gesendet werden.

Senden einer Follow-up-Nachricht

Um eine Follow-up-Nachricht zu senden, sende an die Send API eine POST-Anfrage. Verwende dazu das über den Webhook erhaltene one_time_notif_token und den message.text im Hauptteil der Anfrage:

curl -X POST -H "Content-Type: application/json" -d '{
  "recipient": {
    "one_time_notif_token":"<ONE_TIME_TOKEN>"
  },
  "message": {
    "text":"<MESSAGE_CONTENT>"
  }
}' "https://graph.facebook.com/v21.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"

Um eine Rich-Content-Nachricht zu senden, ersetze den Text durch Rich Content. Eine umfassende Liste unterstützter Nachrichtentypen findest du in der Send API-Referenz. Das one_time_notif_token kann nur einmal verwendet werden und verliert seine Gültigkeit, sobald eine Nachricht erfolgreich gesendet wurde.

Webhook-Events

Wenn der*die Nutzer*in einer Benachrichtigung einem bestimmten Update zustimmt, erhältst du ein Webhook-Event mit payload und one_time_notif_token. Du musst die Payload ebenso wie das Token speichern, um eine Follow-up-Nachricht senden zu können, sobald die entsprechenden Informationen verfügbar sind. Beachte, dass es keine separate API gibt, um eine Liste der one_time_notif_token abzurufen. Daher ist es wichtig, die Webhook-Informationen nach Erhalt zu verarbeiten und zu speichern. Jedes Token kann nur einmal verwendet werden und verfällt innerhalb eines Jahres nach Erstellung.

{
   "sender": {
     "id":"<PSID>"
   },
   "recipient": {
     "id":"<PAGE_ID>"
   },
   "timestamp":1458692752478,
   "optin": {
     "type": "one_time_notif_req",
     "payload": "<USER_DEFINED_PAYLOAD>",
     "one_time_notif_token":"<ONE_TIME_TOKEN>",
   }
}

Begrenzungen und Einschränkungen

• Verwende das Payload-Feld nicht zum Senden von Passwörtern, Zugangsdaten von Nutzer*innen, personenbezogenen Informationen von Nutzer*innen (d. h. Informationen wie Namen oder E-Mail-Adressen, die auch einzeln zur Identifikation einer Person bzw. Kontaktaufnahme mit dieser verwendet werden können) oder sonstigen vertraulichen Informationen (wie Gesundheits-, Finanz-, Zahlungs- oder Karteninhaberdaten sowie anderen Arten von Informationen, die nach geltendem Recht als vertraulich eingestuft werden).
• Die Anzahl an Anfragen für einmalige Benachrichtigungen unterliegt einer Ratenbegrenzung, um ein negatives Nutzer*innenerlebnis zu vermeiden.

FAQ

Weitere Informationen findest du auf unserer Seite mit häufig gestellten Fragen.