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.
To retrieve a user’s profile information, you need to have Advanced Access for the Business Asset User Profile Access feature.
Though a PSID may be valid, in some cases it may not be able to be used to retrieve a person's profile information. For example PSIDs associated with Instant Games Pages are not accessible via the User Profile 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 apps to initiate a conversation without granting the app authorization to access the person's public profile. In those cases, the app will be granted permission to access the person's profile after the person replied to the initial message. Notable situations where a person may initiate a conversation with the app, 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.
In this case, the API will return the error code 2018218
along with the message 'No profile available for this user.'
Apps may retrieve the id
, name
, first_name
, last_name
, and profile_pic
fields for users who have made this information public and have opted-in to your Page. For apps of type Business, the app must first be approved for the Business Asset User Profile Access feature.
Apps can query via the API, which fields are available for a given Page. See Feature Review API.
The following profile fields can be requested:
Field Name | Description | Feature Access |
---|---|---|
| The user's PSID | Granted with Business Asset User Profile Access. |
| The user's first and last name | Granted with Business Asset User Profile Access. |
| First name | Granted with Business Asset User Profile Access. |
| Last name | Granted with Business Asset User Profile Access. |
| URL to the Profile picture. The URL will expire. | Granted with Business Asset User Profile Access. |
| Locale of the user on Facebook. For supported locale codes, see Supported Locales. | This Page level feature needs approval by Facebook |
| Timezone, number relative to GMT | This Page level feature needs approval by Facebook |
| Gender | This Page level feature needs approval by Facebook |
The permissions shown above are required at both the app-level and Page-level in order for the fields to be successfully retrieved. App-level review is mandatory. At Page-level these permissions are granted by default, however 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 the app is able to access 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 the app is unable to access 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 Instant Games. | The User Profile API is not available for PSIDs associated with Instant Game Pages. |
| No profile available for this user. | If the person signed-up to Messenger using a phone number, their profile information will not be available via the User Profile API. |
| Insufficient permission to access user profile. | The app calling the User Profile API has not been granted the permissions needed to access one or more of the requested fields. For more information, see Available Profile Filelds. |