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

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