Messenger-Plattform

Send API-Referenz

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

Erstellen

Erstelle und sende Nachrichten an deine Kundschaft oder an Personen mit Interesse an deiner Facebook-Seite.

Bevor du beginnst

Voraussetzungen:

  • Ein Seiten-Zugriffsschlüssel, der von einer Person angefordert wurde, die die MESSAGE-Aufgabe für die Seite ausführen kann.
  • Die Berechtigung pages_messaging.
  • Der*die Empfänger*in der Nachricht muss deiner Seite innerhalb der letzten 24 Stunden eine Nachricht gesendet haben oder zugestimmt haben, außerhalb des üblichen 24-Stunden-Messaging-Fensters Nachrichten von deiner Seite zu erhalten.

Einschränkungen

  • Nachrichtentags können nicht verwendet werden, um Werbeinhalte zu versenden.

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 einer Person eine Nachricht zu senden, sende eine POST-Anfrage mit den eingestellten Parametern messaging_type und recipient und dem Nachrichteninhalt an den /PAGE-ID/messsages-Endpunkt.

Für bessere Lesbarkeit formatiert.

Im Folgenden siehst du ein Beispiel für eine Antwort auf die Nachricht einer Person, wobei die von deiner Seite gesendete Nachricht nur Text umfasst.

curl -X POST "https://graph.facebook.com/v21.0/{PAGE_ID}/messages" \
      -d "recipient={'id':'{PSID}'}" \
      -d "messaging_type=RESPONSE" \
      -d "message={'text':'hello, world'}" \
      -d "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 sein.

  • attachment-Objekt: Gibt eine Vorschau der URL. Wird zum Senden von Nachrichten mit Medien oder strukturierten Nachrichten verwendet. text oder attachment muss festgelegt sein.

    • type: Art des Anhangs. Möglich ist audio, file, image, template oder video. Maximale Dateigröße: 25 MB
    • payload: Ein Objekt, das Vorlageninhalt oder Dateiinhalt beinhaltet.

  • metadata: Ein String mit zusätzlichen Daten, die du an den message_echo-Webhook weitergeben möchtest. Muss weniger als 1.000 Zeichen umfassen.

  • quick_replies: Ein Array mit Schnellantworten, die als Nachricht gesendet werden können.
  • text: Eine Nachricht, die nur Text enthält. Muss im UTF-8-Format vorliegen und weniger als 2.000 Zeichen umfassen.

messaging_type

enum

Erforderlich

Die Art der gesendeten Nachricht.

  • RESPONSE: Die Nachricht ist eine Antwort auf eine empfangene Nachricht. Dazu gehören Werbe- und andere Nachrichten, die innerhalb des standardmäßigen 24-Stunden-Zeitfensters gesendet werden. Du kannst das Tag beispielsweise verwenden, um Nutzer*innen 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. Dazu gehöre Werbe- und andere Nachrichten, die innerhalb des standardmäßigen 24-Stunden-Zeitfensters gesendet werden.
  • MESSAGE_TAG: Die Nachricht ist keine Werbenachricht und wird außerhalb des standardmäßigen 24-Stunden-Zeitfensters mit einem Nachrichten-Tag gesendet. Die Nachricht muss dem zulässigen Anwendungsfall für das Tag entsprechen.

notification_type

Enum

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

  • NO_PUSH: Keine Benachrichtigung.
  • REGULAR (Standard): Ton oder Vibration, wenn eine Person eine Nachricht erhält.
  • SILENT_PUSH: Nur auf dem Bildschirm angezeigte Benachrichtigung.

recipient

Objekt

Erforderlich

Die Person, die die von deiner Seite versendete Nachricht empfängt.

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

sender_action

Enum

Das im Messaging-Fenster angezeigte Aktionssymbol, das die Aktion darstellt, mit der die Seite auf eine Nachricht reagiert, die sie von einer Person erhalten hat.

  • typing_on: Zeige die „Tippt“-Bubble an, während die Seite eine Antwort vorbereitet.
  • typing_off: Zeige die „Tippt“-Bubble nicht an.
  • mark_seen: Zeige das „Gesehen“-Symbol für Nachrichten an, die von der Seite gesehen wurde.

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

tag

Enum

Ein Tag, das deiner Seite ermöglicht, außerhalb des standardmäßigen 24-Stunden-Fensters eine Nachricht an eine Person zu senden.

  • ACCOUNT_UPDATE: Taggt die Nachricht, die du an deine*n Kund*in sendest, als nicht-wiederholtes Update zu seiner*ihrer App oder seinem*ihrem Konto. Zulässige Anwendungsfälle anzeigen.

    Nicht verfügbar für Instagram Messaging API.

  • CONFIRMED_EVENT_UPDATE: Taggt die Nachricht, die du an deine*n Kund*in sendest, als Erinnerung an ein anstehendes Event oder als Update zu einem laufenden Event, für das der*die Kund*in registriert ist. Zulässige Anwendungsfälle anzeigen.

    Nicht verfügbar für Instagram Messaging API.

  • CUSTOMER_FEEDBACK: Taggt die Nachricht, die du an deine*n Kund*in sendest, als Kund*innenbefragung. Kund*innen-Befragungen müssen innerhalb von 7 Tagen nach der letzten Nachricht des*der Kund*in gesendet werden. Zulässige Anwendungsfälle anzeigen.

    Nicht verfügbar für Instagram Messaging API.

  • HUMAN_AGENT – Erforderlich für Instagram Messaging API. Wenn dieses Tag zu einer Nachricht an eine*n Kund*in hinzugefügt wird, kann ein*e menschliche*r Mitarbeiter*in auf die Nachricht einer Person antworten. Nachrichten können innerhalb von 7 Tagen nach der Nachricht einer Person gesendet werden. Der Human-Agent-Support ist für Probleme vorgesehen, die nicht innerhalb des standardmäßigen Nachrichtenfensters gelöst werden können. Zulässige Anwendungsfälle anzeigen.
    • Apps müssen über das Developer App-Dashboard die Berechtigung Human Agent anfordern. Navigiere zu „App-Dashboard“ -> „App Review“ -> „Berechtigungen & Features“ -> „Human Agent“. Apps, die bereits für den Beta-Zugriff auf die Berechtigung „Human Agent“ zugelassen wurden, müssen den Zugriff nicht noch einmal beantragen.

    Die Berechtigung Human Agent ist mit Standardzugriff oder im Entwicklungsmodus nicht verfügbar. Du musst erst den App Review-Prozess durchlaufen, bevor du das Tag „Human Agent“ verwenden kannst. Gib bei deiner Einreichung für den App Review klare Anweisungen und demonstriere, wie du das Tag „Human Agent“ in deinen Erlebnissen nutzen möchtest.

  • POST_PURCHASE_UPDATE: Taggt die Nachricht, die du an deine*n Kund*in sendest, als Update zu einem kürzlich von der Person getätigten Kauf. Zulässige Anwendungsfälle anzeigen.

    Nicht verfügbar für Instagram Messaging API.

Verwendung von Nachrichten-Tags

In der folgenden Tabelle sind die Arten von Nachrichten für jedes Nachrichten-Tag aufgeführt.

Nachrichten-TagNutzung:

ACCOUNT_UPDATE

Zulässige Nutzungen

  • Eine Benachrichtigung über eine Statusänderung für einen Antrag bzw. eine Bewerbung, z. B. für eine Kreditkarte oder eine Stelle
  • Eine Benachrichtigung über verdächtige Aktivitäten, z. B. Hinweise auf Betrug

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)
  • Aufrufe zu Umfragen oder Feedback, die nicht mit einer vorherigen Interaktion im Messenger in Verbindung stehen

Nicht verfügbar für Instagram Messaging API.

CONFIRMED_EVENT_UPDATE

Zulässige Nutzungen

  • Eine Erinnerung an einen bevorstehenden Kurs, Termin oder eine Veranstaltung, den bzw. die eine Person geplant hat
  • Eine Bestätigung für eine Reservierung oder Teilnahme an einer Veranstaltung oder einem Termin, für die bzw. den die Person zugesagt hat
  • Eine Benachrichtigung zu einer Abholung oder einer geplanten Reise der Person, z. B. Ankunft, Stornierung, Verzögerung bei der Gepäckausgabe oder sonstige Änderungen des Reisestatus

Unzulässige Nutzungen (nicht vollständig)

  • Werbeinhalte, die unter anderem Deals, Angebote, Coupons und Rabatte enthalten
  • Inhalt bezüglich einer Veranstaltung, für die der*die Nutzer*in nicht zugesagt hat (z. B. Erinnerungen zum Kauf von Tickets, Cross-Selling anderer Veranstaltungen, Tourpläne etc.)
  • Nachrichten zu vergangenen Veranstaltungen
  • Aufrufe zu Umfragen oder Feedback, die nicht mit einer vorherigen Interaktion im Messenger in Verbindung stehen

Nicht verfügbar für Instagram Messaging API.

CUSTOMER_FEEDBACK

Zulässige Nutzungen

  • Eine Umfrage für Feedback zur Kaufunterstützung
  • Eine Umfrage für Feedback zu einer Veranstaltung
  • Produktbewertungen

Unzulässige Nutzungen (nicht vollständig)

  • Das Tag kann nur mit der Kund*innenfeedback-Vorlage verwendet werden. Die Verwendung in jeder anderen Form ist untersagt und schlägt fehl.

Nicht verfügbar für Instagram Messaging API.

HUMAN_AGENT

Zulässige Nutzungen

  • Unterstützung durch eine*n Vermittler*in bei Problemen, die nicht im standardmäßige 24-Stunden-Nachrichtenfenster behoben werden können. z. B. eine Behebung von Problemen außerhalb der normalen Geschäftszeiten oder von Problemen, deren Lösung länger als 24 Stunden dauert

Unzulässige Nutzungen (nicht vollständig)

  • Automatisierte Nachrichten
  • Inhalt, der nichts mit der Nutzer*innenanfrage zu tun hat

Erforderlich für Instagram Messaging API.

POST_PURCHASE_UPDATE

Zulässige Nutzungen

  • Eine Bestätigung für eine Transaktion, wie z. B. Rechnungen oder Zahlungsbelege
  • Ein Status-Update zu einer Lieferung, z. B. Produkte im Versand, versandt, ausgeliefert oder verspätet
  • Ein Status-Update, das eine Person auffordert, Maßnahmen für eine von ihr aufgegebene Bestellung zu ergreifen, wie z. B. eine abgelehnte Kreditkarte, Artikel mit Rückstand oder sonstige Updates zur Bestellung, die eine Handlung erforderlich machen

Unzulässige Nutzungen (nicht vollständig)

  • Werbeinhalte, die unter anderem Deals, Angebote, Coupons und Rabatte enthalten
  • Nachrichten für das Cross-Selling oder Upselling von Produkten oder Dienstleistungen
  • Aufrufe zu Umfragen oder Feedback, die nicht mit einer vorherigen Interaktion im Messenger in Verbindung stehen

Nicht verfügbar für Instagram Messaging API.

Lesen

Diesen Vorgang kannst du nicht für diesen Endpunkt ausführen.

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

Aktualisieren

Diesen Vorgang kannst du nicht für diesen Endpunkt ausführen.

Löschen

Diesen Vorgang kannst du nicht für diesen Endpunkt ausführen.

Siehe auch

Unterstützung für Entwickler*innen