Appearance
User Profile API
Updated: Mar 18, 2026
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.
Requirements
- To retrieve a user's profile information, you need to have Advanced Access for the Business Asset User Profile Access feature. Some fields require additional permissions for access.
Limitations
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.
User Opt-in
The following events will authorize your Messenger bot to access a person's profile information:
- The person starts the conversation via a welcome screen and tapped the "Get Started" button.
- The person starts the conversation by clicking a "Send to Messenger" button.
- The person starts the conversation by sending a message.
- The person starts the conversation by accepting a Page's message request.
- Your Messenger bot uses the
askPermission()function of the Messenger Extensions SDK in the webview to ask for theuser_profilepermission. - For Business apps, the Business Asset User Profile Access feature is additionally required, and can be applied for via App Review.
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:
- Conversations started via the Checkbox Plugin where the person did not respond on Messenger.
- Interactions with Ads that Click to Messenger before the person has replied on Messenger
Profile Unavailable
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.'
Available Profile Fields
Apps that have received App Review approval for the required feature and permission may retrieve the following fields for users who have made this information public and have opted-in to your Page.
| Field Name | Description | Feature or Permission Required for Access |
|---|---|---|
id | The user's PSID | Business Asset User Profile Access feature |
name | The user's first and last name | Business Asset User Profile Access feature |
first_name | First name | Business Asset User Profile Access feature |
last_name | Last name | Business Asset User Profile Access feature |
profile_pic | URL to the Profile picture. The URL will expire. | Business Asset User Profile Access feature |
locale | Locale of the user on Facebook. For supported locale codes, see Supported Locales. | pages_user_locale permission |
timezone | Timezone, number relative to GMT | pages_user_timezone permission |
gender | Gender | pages_user_gender permission |
Requesting feature access to user fields for the Page
- Go to Page Settings > Advanced Messaging
- Under 'Info About People' select the field and click the 'Request' button.
Retrieving a Person's Profile
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.