User Profile API

Breaking Change Notice - Extended Profile Field Permissions

The following changes to the Messenger Platform's User Profile API have been announced:

  • Default profile fields: By default, the API will only return name, first_name, last_name, and profile_pic fields.
  • App-level extended profile field permissions: To access additional user profile fields, app developers must apply for each field in the Messenger Platform tab of the app console. For more information, see Available Profile Fields below.
  • Deprecated fields: The last_ad_referral and is_payment_enabled fields are now deprecated, and will be removed from the API on October 30, 2018.

For apps created before the release of Graph API v3.1 on July 26, 2018, these changes will go into effect on January 8, 2019. Apps must be resubmitted and be approved for extended profile fields before this date. Apps that qualify for this grace period must make all Messenger User Profile API calls to Graph API v3.0 or below to continue to access extended permissions.

For apps created after the release of Graph API v3.1 on July 26, 2018, these changes are in effect immediately.

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

Contents

Availability

Though you may have a PSID, you may not have permission or be able to retrieve a person's profile information.

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 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:

Profile Unavailable

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.'

Available Profile Fields

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

id

The user's PSID

N/A

name

The user's first and last name

N/A

first_name

First name

N/A

last_name

Last name

N/A

profile_pic

Profile picture

N/A

locale

Locale of the user on Facebook. For supported locale codes, see Supported Locales.

pages_user_locale

timezone

Timezone, number relative to GMT

pages_user_timezone

gender

Gender

pages_user_gender

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 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.

Last Ad Referral - DEPRECATED

This profile field was deprecated on July 26, 2018. Apps that were created before this date will be able to continue accessing this field until October 30, 2018.

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.

To make it easier for developers to identify which sent a person to their bot, the details of the last click-to-Messenger 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 click-to-Messenger ad.

Example

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

Error Codes

Code Message Reason

2018218

No profile available for this user.

If the user registered for Messenger with a phone number, no profile information is available.

2018247

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.