User Profile API

The User Profile API allows you to use a PSID to retrieve profile information that can be used to personalize the experience of people interacting with your Messenger bot.



Though you may have a PSID, this does not mean you have permission to retrieve a person's profile information.

The following events will authorize your Messenger bot to access 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 tapping a button.
  • Your Messenger bot uses the askPermission() function of the Messenger Extensions SDK in the webview to ask for the user_profile permission.

Notable situations where a person may start a conversation with your Messenger bot but not authorize profile permission include the following:

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 "<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": "",
  "locale": "en_US",
  "timezone": -7,
  "gender": "male",
  "last_ad_referral": {
    "source": "ADS",
    "type": "OPEN_THREAD",
    "ad_id": "6045246247433"

If you are not allowed to view the person's profile, an empty object is returned.

Available Profile Fields

The following profile fields can be requested:

Field Name Description


First name


Last name


Profile picture


Locale of the user on Facebook


Timezone, number relative to GMT




Is the user eligible to receive messenger platform payment messages


Details of the last Messenger Conversation Ad user was referred from

Last Ad Referral

To make it easier for developers to identify which sent a person to their bot, the details of the last ad the person was referred by may be requested in the last_ad_referral field.

The last_ad_referral field is only available if the referrer was a Messenger Conversation Ad.


  "first_name": "Peter",
  "last_name": "Chang",
  "last_ad_referral": {
    "source": "ADS",
    "type": "OPEN_THREAD",
    "ad_id": "6045246247433"