Messenger-Plattform

Send API-Referenz

Die Send API ist die Haupt-API, die zum Senden von Nachrichten an Nutzer verwendet wird, einschließlich Text, Anhängen, Vorlagen, Handlungen des Senders und vielem mehr.

Erstellen

Du erstellst und sendest Nachrichten an deine Kunden und an Personen, die an deiner Facebook-Seite interessiert sind.

Bevor du beginnst

Voraussetzungen:

  • Ein Seiten-Zugriffsschlüssel, der von einer Person angefordert wird, die die MESSAGE-Aufgabe auf der Seite ausführen kann
  • Die pages_messaging-Berechtigung
  • Der Nachrichtenempfänger muss deiner Seite innerhalb der letzten 24 Stunden eine Nachricht gesendet haben oder zugestimmt haben, Nachrichten von deiner Seite außerhalb des 24-Stunden-Nachrichtenfensters zu erhalten

Einschränkungen

  • Nachrichten-Tags können nicht für das Senden von Werbeinhalten verwendet werden.

Beachte, dass die Send API recipient_id in der Antwort auf gesendete Nachrichten nicht enthält, die recipient.user_ref oder recipient.phone_number verwenden, um den*die Nachrichtenempfänger*in zu identifizieren.

Beispielanfrage

Um eine Nachricht an eine Person zu senden, sende eine POST-Anfrage mit dem Nachrichteninhalt an den /PAGE-ID/messsages-Endpunkt und lege die Parameter messaging_type und recipient fest.

Für bessere Lesbarkeit formatiert.

Das folgende Beispiel zeigt eine Antwort auf die Nachricht einer Person, wobei die Nachricht, die deine Seite sendet, nur aus Text besteht.

curl -i -X POST "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/messages
    ?recipient={'id':'PSID'}
    &messaging_type=RESPONSE
    &message={'text':'hello,world'}
    &access_token=PAGE-ACCESS-TOKEN

Wenn der Vorgang erfolgreich verläuft, erhält deine App die folgende JSON-Antwort:

{
  "recipient_id": "PAGE-SCOPED-ID",
  "message_id": "AG5Hz2U..."
}

Parameter

ParameterBeschreibung

message

Objekt

Die Art der Nachricht, die deine Seite sendet. Bei Verwendung dieses Parameters muss entweder text oder attachement festgelegt werden.

  • attachment-Objekt – Zeigt eine Vorschau der URL an. Wird verwendet, um Nachrichten mit Medien oder strukturierte Nachrichten zu senden. text oder attachment muss festgelegt sein.

    • type – Art des Anhangs. Entweder audio, file, image, template oder video. Die maximale Dateigröße beträgt 25 MB.
    • payload – Ein Objekt, das einen Vorlageninhalt oder Dateiinhalt enthält.

  • metadata – Ein String mit zusätzlichen Daten, die im message_echo-Webhook übergeben werden sollen. Muss weniger als 1.000 Zeichen umfassen.

  • quick_replies – Ein Array von Schnellantworten, die in einer Nachricht gesendet werden sollen.
  • text – Eine Nachricht, die nur Text enthält. Muss im UTF-8-Format vorliegen und ist auf 2.000 Zeichen beschränkt.

messaging_type

Enum

Erforderlich

Der Typ der gesendeten Nachricht.

  • RESPONSE – Die Nachricht ist eine Antwort auf eine empfangene Nachricht. Das beinhaltet Werbe- und andere Nachrichten, die innerhalb des standardmäßigen 24-Stunden-Nachrichtenfensters gesendet werden. Du kannst das Tag beispielsweise verwenden, um dem Nutzer in deiner Antwort eine Reservierung zu bestätigen oder eine Statusänderung mitzuteilen.
  • UPDATE – Die Nachricht wird proaktiv gesendet und ist keine Antwort auf eine zuvor empfangene Nachricht. Das beinhaltet Werbe- und andere Nachrichten, die innerhalb des standardmäßigen 24-Stunden-Nachrichtenfensters gesendet werden.
  • MESSAGE_TAG – Die Nachricht ist keine Werbenachricht und wird außerhalb des standardmäßigen 24-Stunden-Nachrichtenfensters mit einem Nachrichten-Tag gesendet. Die Nachricht muss dem zulässigen Anwendungsfall für das Tag entsprechen.

notification_type

Enum

Art der Push-Benachrichtigung, die eine Person erhält.

  • NO_PUSH – Keine Benachrichtigung
  • REGULAR (Standard) – Ton oder Vibration beim Empfang einer Nachricht
  • SILENT_PUSH – Nur Benachrichtigung auf dem Bildschirm

recipient

Objekt

Erforderlich

Die Person, die die von deiner Seite gesendete Nachricht empfängt

  • id – Die seitenspezifische ID der Person, die zum Senden einer Nachricht als Antwort auf eine innerhalb der letzten 24 Stunden von deiner Seite empfangenen Nachricht verwendet wird, oder der Person, die zugestimmt hat, Nachrichten von deiner Seite außerhalb des standardmäßigen 24-Stunden-Nachrichtenfensters zu erhalten.
  • user_ref – Die Referenz für die Person, die zum Senden einer Nachricht als Antwort auf ein Auswahlfeld oder ein Customer Chat-Plugin verwendet wird.
  • comment_id – Die ID für den Kommentar, der verwendet wird, um eine Nachricht als private Antwort als Reaktion auf einen Besucherkommentar zu deinem Seitenbeitrag zu senden.
  • post_id – Die ID für den Seitenbeitrag, der verwendet wird, um eine Nachricht als private Antwort als Reaktion auf einen Besucherkommentar auf deiner Seite zu senden.

sender_action

Enum

Das Handlungssymbol, das im Nachrichtenfenster angezeigt wird und die Handlung darstellt, die von der Seite als Reaktion auf eine Nachricht durchgeführt wurde, die die Seite von einer Person erhalten hat.

  • typing_on – „Schreibt...“-Sprechblase anzeigen, wenn die Seite eine Antwort vorbereitet
  • typing_off – „Schreibt...“-Sprechblase nicht anzeigen
  • mark_seen – „Gesehen“-Symbol für Nachrichten anzeigen, die von der Seite gesehen wurden

Kann nur mit dem recipient-Parameter gesendet werden. Kann nicht mit dem message-Parameter gesendet werden, sondern nur als separate Anfrage.

tag

Enum

Ein Tag, mit dem deine Seite außerhalb des standardmäßigen 24-Stunden-Nachrichtenfensters eine Nachricht an eine Person senden kann.

  • ACCOUNT_UPDATE – Markiert die Nachricht, die du an einen Kunden sendest, als einmalige Aktualisierung seiner Anwendung oder seines Kontos. Zulässige Nutzungen anzeigen.

    Nicht verfügbar für die Instagram Messaging-API.

  • CONFIRMED_EVENT_UPDATE – Markiert die Nachricht, die du an deinen Kunden sendest, als Erinnerung an ein bevorstehendes Ereignis oder eine Aktualisierung für ein laufendes Ereignis, für das der Kunde registriert ist. Zulässige Nutzungen anzeigen.

    Nicht verfügbar für die Instagram Messaging-API.

  • CUSTOMER_FEEDBACK – Markiert die Nachricht, die du an deinen Kunden sendest, als Umfrage für Kundenfeedback . Nachrichten zu Kundenfeedback müssen innerhalb von sieben Tagen nach der letzten Nachricht des Kunden erfolgen. Zulässige Nutzungen anzeigen.

    Nicht verfügbar für die Instagram Messaging-API.

  • HUMAN_AGENT – Erforderlich für die Instagram Messaging-API. Wenn dieses Tag zu einer Nachricht hinzugefügt wird, die an eine Person gesendet wird, kann ein Mitarbeiter auf die Nachricht der Person antworten. Nachrichten können innerhalb von sieben Tagen nach der Nachricht der Person gesendet werden. Support durch einen Mitarbeiter sollte bei Problemen erfolgen, die nicht im Standard-Nachrichtenfenster gelöst werden können. Zulässige Nutzungen anzeigen.
    • Apps müssen die Human Agent-Berechtigung über das Dashboard für die Entwickler-App beantragen. Navigiere zu App-Dashboard -> App Review -> Berechtigungen und Funktionen -> Human Agent. Apps, die bereits für den Beta-Zugriff auf die Human Agent-Berechtigung berechtigt waren, müssen keinen erneuten Zugriff beantragen.

    Human Agent-Berechtigung ist nicht im Standardzugriffs- oder Entwicklungsmodus verfügbar. Du musst den App Review-Prozess abschließen, um das Human Agent-Tag nutzen zu können. Bitte gib bei der App Review-Einreichung klare Anweisungen und eine Demonstration dafür, wie du das Human Agent-Tag in deinen Erlebnissen nutzen möchtest.

  • POST_PURCHASE_UPDATE – Markiert die Nachricht, die du an deinen Kunden sendest, als eine Aktualisierung für einen kürzlich getätigten Kauf des Kunden. Zulässige Nutzungen anzeigen.

    Nicht verfügbar für die Instagram Messaging-API.

Nutzungen für Nachrichten-Tags

In der folgenden Tabelle sind die Nachrichtentypen für die einzelnen Nachrichten-Tags aufgeführt.

Nachrichten-TagsNutzung

ACCOUNT_UPDATE

Zulässige Nutzungen

  • Eine Benachrichtigung über eine Statusänderung für eine Bewerbung, z. B. für eine Kreditkarte oder eine Stellenbewerbung
  • Eine Benachrichtigung über verdächtige Aktivitäten, z. B. Betrugswarnungen

Unzulässige Nutzungen (nicht vollständig)

  • Werbeinhalte, insbesondere u. a. Angebote, Promotions, Gutscheine und Rabatte, wiederkehrende Inhalte (z. B. Kontoauszug liegt bereit, Rechnung ist fällig, neue Stellenangebote)
  • Aufforderungen zu Studien, Umfragen oder Bewertungen, die in keinem Zusammenhang mit einer vorangegangenen Interaktion im Messenger stehen

Nicht verfügbar für die Instagram Messaging-API.

CONFIRMED_EVENT_UPDATE

Zulässige Nutzungen

  • Eine Erinnerung für einen bevorstehenden Kurs, Termin oder eine Veranstaltung, sofern von Nutzer geplant
  • Eine Reservierungs- oder Teilnahmebestätigung des Nutzers für eine Veranstaltung oder einen Termin
  • Eine Benachrichtigung für den Transport oder die geplante Reise eines Nutzers, z. B. Ankunft, Stornierung, Gepäckverspätung oder sonstige Änderungen des Reisestatus

Unzulässige Nutzungen (nicht vollständig)

  • Werbeinhalte, einschließlich, aber nicht beschränkt auf, Angebote, Promotions, Gutscheine und Rabatte
  • Inhalte, die sich auf eine Veranstaltung beziehen, für die sich der Nutzer nicht angemeldet hat (z. B. Erinnerungen an den Kauf von Veranstaltungstickets, Cross-Selling von anderen Veranstaltungen, Tourpläne usw.)
  • Nachrichten, die sich auf vergangene Veranstaltungen beziehen
  • Aufforderungen zu Studien, Umfragen oder Bewertungen, die in keinem Zusammenhang mit einer vorangegangenen Interaktion im Messenger stehen

Nicht verfügbar für die Instagram Messaging-API.

CUSTOMER_FEEDBACK

Zulässige Nutzungen

  • Eine Umfrage für Feedback zum Support beim Einkaufen
  • Eine Umfrage für Feedback zu Veranstaltungen
  • Produktbewertungen

Unzulässige Nutzungen (nicht vollständig)

  • Das Tag kann nur mit der Kundenfeedback-Vorlage verwendet werden. Jede andere Form der Verwendung ist verboten und schlägt fehl.

Nicht verfügbar für die Instagram Messaging-API.

HUMAN_AGENT

Zulässige Nutzungen

  • Unterstützung durch einen Mitarbeiter bei Problemen, die nicht innerhalb des standardmäßigen 24-Stunden-Nachrichtenfensters gelöst werden können, z. B. bei Problemen außerhalb der normalen Geschäftszeiten oder bei Problemen, deren Lösung mehr als 24 Stunden in Anspruch nimmt

Unzulässige Nutzungen (nicht vollständig)

  • Automatisierte Nachrichten
  • Inhalte, die sich nicht auf Nutzeranfragen beziehen

Erforderlich für die Instagram Messaging-API.

POST_PURCHASE_UPDATE

Zulässige Nutzungen

  • Eine Bestätigung für eine Transaktion, z. B. Rechnungen oder Zahlungsbelege
  • Ein Status-Update für eine Lieferung, z. B. Produkt auf dem Transportweg, versandt, geliefert oder verspätet
  • Ein Status-Update, das einen Nutzer auffordert, Maßnahmen für eine von ihm aufgegebene Bestellung zu ergreifen, z. B. eine abgelehnte Kreditkarte, nicht mehr vorrätige Artikel oder andere Aktualisierungen, die eine Handlung des Nutzers erfordern

Unzulässige Nutzungen (nicht vollständig)

  • Werbeinhalte, insbesondere u. a. Angebote, Promotions, Gutscheine und Rabatte
  • Nachrichten für das Cross-Selling oder Upselling von Produkten oder Dienstleistungen
  • Aufforderungen zu Studien, Umfragen oder Bewertungen, die in keinem Zusammenhang mit einer vorangegangenen Interaktion im Messenger stehen

Nicht verfügbar für die Instagram Messaging-API.

Lesen

Du kannst diesen Vorgang nicht an diesem Endpunkt durchführen.

Informationen zu Unterhaltungen, an denen deine Seite beteiligt ist, erhältst du in der Referenz zu Seitenunterhaltungen.

Aktualisieren

Du kannst diesen Vorgang nicht an diesem Endpunkt durchführen.

Löschen

Du kannst diesen Vorgang nicht an diesem Endpunkt durchführen.

Siehe auch:

Unterstützung für Entwickler*innen