User Profile API

The User Profile API lets your bot get more information about the user and personalize their experience.

Calling this API requires passing the user's PSID (page-scoped user ID). You might find the PSID in the message or postback webhooks, or via getContext() in Messenger Extensions inside your bot's webview.

When is a User's Profile Available?

Though you may have a PSID, this does not mean that the user profile is available.

The following events will authorize the bot to have profile permissions:

  • The user entered the bot via a welcome screen and tapped the "Get Started" button.
  • The user sent a message to the bot or tapped a button in the thread.
  • Inside the webview, the bot specifically asked for (and was granted) the user_profile permission.

Notable situations where the user may interact with the bot but not yet have authorized profile permission include interacting with the bot via a web plugin, customer matching, Messenger Conversation Ads, opening shared content from the bot, and opening a Chat Extension they have never used before.

Request

To use the User Profile API, make a GET call to https://graph.facebook.com/v2.6/<USER_ID>?access_token=PAGE_ACCESS_TOKEN.

Example

curl -X GET "https://graph.facebook.com/v2.6/<USER_ID>?fields=first_name,last_name,profile_pic,locale,timezone,gender&access_token=PAGE_ACCESS_TOKEN"    

Fields

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

Response

A successful User Profile API request returns a json string with the requested details about the user.

Example

{
  "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"
}    

The information at this API is only available after a person has sent a message to your bot or clicked the "Send to Messenger" plugin. If you call the API before these actions, then you will receive an empty result. You will also receive an empty result if a person has revoked platform permissions on Facebook.

{}

Last Ad Referral

To make it easier for developers to identify which ad the user came from, the details of the last ad user was referred from are available in the user profile in "last_ad_referral" field.

Note that this feature is only available for Messenger Conversation Ads.

Example

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