Messenger Platform

OverviewDocumentation
 
 
 

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

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

Field Name Description

first_name

First name

last_name

Last name

profile_pic

Profile picture

locale

Locale of the user on Facebook

timezone

Timezone, number relative to GMT

gender

Gender

is_payment_enabled

Is the user eligible to receive messenger platform payment messages

last_ad_referral

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.

Example

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