The User Profile API allows you to use a Page-scoped ID (PSID) to retrieve user profile information that can be used to personalize the experience of people interacting with your Messenger.
Though you may have a PSID, you may not have permission or be able to retrieve a person's profile information. For example Instant Game Pages are not allowed to use this API.
The following events will authorize your Messenger bot to access a person's profile information:
askPermission() function of the Messenger Extensions SDK in the webview to ask for the user_profile permission.Some entry points allow you or people to initiate a conversation without giving your bot authorization to the person's public profile. In those cases, your Messenger bot will be granted permission to access user profile after the user replied to the initial message. Notable situations where a person may initiate a conversation with your Messenger bot, but not authorize profile permission include the following:
Currently, the User Profile API does not support retrieving profile information for Messenger accounts that were created using a phone number instead of a Facebook account.
In this case, the API will return error code 2018218 with the message 'No profile available for this user.'
By default, your apps may retrieve the id, name, first_name, last_name, and profile_pic fields for user's that have made this information public and have opted-in to your bot.
Beginning July 26, 2018, apps must request access to all other profile fields as part of the app review process. To submit for access to profile fields, add the permissions you would like to request when you submit your app in the Messenger Platform tab of the app console.
The following profile fields can be requested:
| Field Name | Description | Permission |
|---|---|---|
| The user's PSID | N/A |
| The user's first and last name | N/A |
| First name | N/A |
| Last name | N/A |
| URL to the Profile picture. The URL will expire. | N/A |
| Locale of the user on Facebook. For supported locale codes, see Supported Locales. |
|
| Timezone, number relative to GMT |
|
| Gender |
|
The above permissions are needed at both the app-level and Page-Level to be able to retrieve the fields. App-Level review is mandatory. At Page-Level these permissions are granted by default, yet we recommend that page admins proactively do a Page-level submission explaining why they need them on that particular page.
To use the User Profile API, send a GET request with the profile fields you want for the person:
curl -X GET "https://graph.facebook.com/<PSID>?fields=first_name,last_name,profile_pic&access_token=<PAGE_ACCESS_TOKEN>"If you are allowed to view the person's profile, the User Profile API will return a JSON string with the requested fields from the person's profile.
{
"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",
}If you are not allowed to view the person's profile, an empty object is returned.
This profile field has been deprecated.
The ad_id of the last ad referral will continue to be provided in the messaging_referrals webhook event when the user enters your bot via a click-to-Messenger ad.
| Code | Message | Reason |
|---|---|---|
| No Permission For Pages Associated to the Instant Game. | Instant game Pages are not allowed to access the User Profile API. |
| No profile available for this user. | If the user registered for Messenger with a phone number, no profile information is available. |
| Insufficient permission to access user profile. | The app requesting the user profile has not been granted to permissions needed to access one or more of the requested fields. For more information, see Available Profile Filelds. |