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.

Contents

• Availability
  • User Opt-in
  • Profile Unavailable
• Retrieving a Person's Profile
• Available Profile Fields
• Last Ad Referral
• Error Codes

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

• Conversations started via a web plugin
• Conversations started via customer matching
• Conversations started via Messenger Conversation Ads
• Conversations started by opening shared content
• Interactions started by opening a Chat Extension.

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

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/v2.6/<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",
  "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:

Last Ad Referral

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.

Example

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

Error Codes