User Profile API

Mit der User Profile API kannst du über eine seitenspezifische ID (PSID) Informationen über ein Benutzer*innenprofil abrufen und so das Erlebnis von Personen personalisieren, die mit deinem Messenger interagieren.

Verfügbarkeit

Um Informationen zu einem Benutzer*innenprofil abzurufen, brauchst du erweiterten Zugriff auf die Funktion Zugriff auf Benutzerprofil mit Business Assets. Manche Felder erfordern zusätzliche Berechtigungen für den Zugriff.

Selbst gültige PSIDs können in manchen Fällen nicht zum Abrufen von Profilinformationen einer Person verwendet werden. Zum Beispiel sind PSIDs, die mit Instant Games-Seiten assoziiert sind, nicht über die User Profile API abrufbar.

Aktivierung durch Benutzer*in

Die folgenden Events autorisieren deinen Messenger-Bot zum Zugriff auf Profilinformationen einer Person:

Die Person beginnt die Unterhaltung über einen Willkommensbildschirm und hat auf den Button „Los geht‘s“ getippt.
Die Person beginnt die Unterhaltung durch Klicken auf einen „An Messenger senden“-Button.
Die Person beginnt die Unterhaltung durch Senden einer Nachricht.
Die Person beginnt die Unterhaltung durch das Annehmen der Nachrichtenanfrage einer Seite.
Dein Messenger-Bot nutzt die askPermission()-Funktion des SDK für Messenger-Erweiterungen in der Webansicht, um die user_profile-Berechtigung anzufragen.
Für Apps des Business-Apps wird zusätzlich die Funktion Zugriff auf Benutzerprofil mit Business Assets benötigt. Diese kann über App-Review beantragt werden.

Manche Eingangspunkte erlauben Apps, eine Unterhaltung zu beginnen, ohne der App die Berechtigung zum Zugriff auf das öffentliche Profil der Person zu gewähren. In solchen Fällen wird der App die Berechtigung zum Zugriff auf das Profil der Person gewährt, nachdem die Person auf die erste Nachricht geantwortet hat. In folgenden Situationen kann eine Person eine Unterhaltung mit der App beginnen, ohne eine Profilberechtigung zu erteilen:

Unterhaltungen, die über das Checkbox-Plugin begonnen wurden und von der Person nicht in Messenger beantwortet wurden.
Interaktionen mit Click-to-Messenger-Anzeigen, bevor die Person in Messenger geantwortet hat

Profil nicht verfügbar

Die User Profile API unterstützt derzeit nicht das Abrufen von Profilinformation für Messenger-Konten, die mithilfe einer Telefonnummer erstellt wurden.

Die API gibt in diesem Fall den Fehlercode 2018218 mit der Meldung „Kein Profil für diese*n Nutzer*in verfügbar" zurück.

Verfügbare Profilfelder

Apps, die eine App Review-Genehmigung für die benötigte Funktion haben und berechtigt sind, können die folgenden Felder von Nutzer*innen abrufen, die diese Informationen öffentlich gemacht und dies für deine Seite aktiviert haben.

Name des Feldes	Beschreibung	Berechtigung
`id`	Seitenspezifische Nutzer-ID	N/V
`name`	Vor- und Nachname des Nutzers	N/V
`first_name`	Vorname	N/V
`last_name`	Nachname	N/V
`profile_pic`	Profilbild	N/V
`locale`	Ländereinstellung des Nutzers auf Facebook	`pages_user_locale`
`timezone`	Zeitzone in Bezug auf GMT	`pages_user_timezone`
`gender`	Geschlecht	`pages_user_gender`

Beantragen des Funktionszugriffs auf Benutzer*innenfelder für die Seite

Gehe zu „Seiteneinstellungen > Erweitertes Messaging“.
Wähle unter „Info zu Personen“ das Feld aus und klicke auf „Anfrage“.

Abrufen des Profils einer Person

Um die User Profile API zu nutzen, sende eine GET-Anfrage mit den gewünschten Profilfeldern für die Person:

curl -X GET "https://graph.facebook.com/<PSID>?fields=first_name,last_name,profile_pic&access_token=<PAGE_ACCESS_TOKEN>"

Wenn die App auf das Profil der Person zugreifen kann, gibt die User Profile API einen JSON-String mit den angefragten Feldern aus dem Profil der Person zurück.

{
  "first_name": "Peter",
  "last_name": "Chang",
  "profile_pic": "https://fbcdn-profile-a.akamaihd.net/hprofile-ak-xpf1/v/t1.0-1/p200x200/13055603_10105219398495383_8237637584159975445_n.jpg?oh=1d241d4b6d4dac50eaf9bb73288ea192&oe=57AF5C03&__gda__=1470213755_ab17c8c8e3a0a447fed3f272fa2179ce",
  "locale": "en_US",
  "timezone": -7,
  "gender": "male",
  "last_ad_referral": {
    "source": "ADS",
    "type": "OPEN_THREAD",
    "ad_id": "6045246247433"
  }
}

Wenn die App nicht auf das Profil der Person zugreifen kann, wird ein leeres Objekt zurückgegeben.

Siehe auch

Fehlercodes der Messenger-Plattform