Adding Social Context to Your Content

The Social Context API lets you easily query for a person's friends' activity around some content within your app. It also lets you easily establish the mutual friends and mutual likes between two people.

This information is available via the context field, which is supported on several object types. Each object supports different context edges as appropriate. These objects are always queried on behalf of a person (with a User Access Token), with the results returned being respective to that user. The set of queryable objects are enumerated below:

  • Pages and Open Graph Objects
  • friends_who_like - The friends of the calling user who have liked this object.
  • video_watch_friends (for video pages) - The friends of the calling user who have watched this object.
  • music_listen_friends (for music pages) - The friends of the calling user who have listened to this object.
  • friends_tagged_at (for places) - The friends of a the calling user who have been tagged at that place.
  • Apps
  • friends_using_app - The friends of the calling user who have logged into the specified app. The specified app can be a different app to the one making the call, as long as they are associated with the same business.
  • Users
  • mutual_friends - The friends that the calling user and the subject user have in common.
  • mutual_likes - An array of the pages the calling user and the subject user have both liked.
  • all_mutual_friends - Facebook friends that the session user and the request user have in common. This includes friends who use the app as well as non-app-using mutual friends.
  • three_degree_mutual_friends - Friends of the viewer who are mutual friends with the target and have the app installed. Note: Access to the Three Degree Mutual Friends API is restricted to a limited set of partners and usage requires prior approval by Facebook.

Querying

When you request the context field for an object, you'll be returned a result containing context edges. Each edge lists a person's friends already using the app, who have taken a given action on the object.

In addition, you can request a summary field, which includes total_count, an integer sum of all the calling user's friends who have performed the action in question - including those who do not use the app.

Permissions

The behavior of the context field respects the same rules for data visibility and user privacy as other Graph API calls. In order for a person to be identifiably returned in a context edge, they must have:

  • Logged into the app.
  • Granted the user_friends permission.
  • Granted the appropriate content permission in order to see the action. For example, to appear in the friends_who_like context edge, each friend has to have granted the app the user_likes permission.

If those conditions are not met, the user will not be identifiably included in the response, and instead will be counted within the summary object's total_count field. Read more about Permissions.

Context on Pages and Open Graph Objects

To surface social context between a person and a Facebook Page or an Open Graph Object, request the context field on the ID of either the page or the object.

On Page and Open Graph nodes, by default, the context field will return the friends_who_like edge. However, depending on the type of the object, additional content is available:

  • If you know the object is a movie, tv show or tv episode, then you may also request the video_watch_friends context edge.
  • If you know the object is a music artist, a song or an album, you could request the music_listen_friends context edge.
  • If you know the object is a place, you could request the friends_tagged_at context edge.

An example query is shown below:

GET /ironman?fields=context.fields(friends_who_like,video_watch_friends) HTTP/1.1
Host: graph.facebook.com

Example response:

{
  "context": {
    "friends_who_like": {
      "data": [
        {
          "id": "202875", 
          "name": "Ravi Grover"
        }, 
        {
          "id": "1207059", 
          "name": "Dhiren Patel"
        }, 
        {
          "id": "185104155", 
          "name": "Brady Voss"
        }, 
        {
          "id": "533875325", 
          "name": "Stephen Doyle"
        }, 
        {
          "id": "843850216", 
          "name": "Aryeh Selekman"
        }
      ], 
      "paging": {
        "next": "https://graph.facebook.com/v2.4/MAaw33efJDbOnAQTTFhTKIqeX4tw4twJA2x4CR/friends_who_like?limit=5&after=ODQzODUwMjE2", 
        "cursors": {
          "before": "MjAyODc1", 
          "after": "ODQzODUwMjE2"
        }
      }, 
      "summary": {
        "social_sentence": "34 of your friends like this.", 
        "total_count": 34
      }
    }, 
    "video_watch_friends": {
      "data": [
        {
          "id": "13930675", 
          "name": "Vadim Lavrusik"
        }, 
        {
          "id": "512256771", 
          "name": "Andrew Rothbart"
        }, 
        {
          "id": "548517159", 
          "name": "Douglas Purdy"
        }, 
        {
          "id": "17202944", 
          "name": "Rose Yao"
        }, 
        {
          "id": "202726", 
          "name": "Alex Himel"
        }
      ], 
      "paging": {
        "next": "https://graph.facebook.com/v2.4/MAaJufefJDbOnAQTTFhTKIqeXkMm1mVfrElwJA2x4CR/video_watch_friends?limit=5&after=MjAyNzI2", 
        "cursors": {
          "before": "MTM5MzA2NzU=", 
          "after": "MjAyNzI2"
        }
      }, 
      "summary": {
        "total_count": 76
      }
    }
  }, 
  "id": "7057882289"
}

Note: The context edges for Pages and Open Graph Objects only include the details of friends who have already logged in to the app from which the call is made. The summary field however, contains the total sum of all the person's friends who have performed the action in question, including those who have not logged in to the associated app.

Context on Apps

To surface social context between a person an an application, request the context field on an Application object.
By default, this will return the friends_using_app context edge.

If you request the context field on the same app ID from which you're making the call, the API will return the subset of a user's friends who also use this app and have granted the user_friends permission. This is equivalent to calling /me/friends.

However, the power of the Social Context API for apps comes when you request the context field on a different app ID. In this case, if the calling app and the subject app are owned by the same Business, the response will include the set of a user's friends who have previously logged in to the subject app. This is particularly valuable for businesses operating multiple apps using Facebook, such as game developers, to enable cross-app promotion.

Note that for a person's friend to be identifiably returned in the friends_using_app context edge when querying for another app, they must have granted the user_friends permission.

Note: The context edges for apps only include the details of friends who have already logged in to the app being queried and have granted the user_friends permission. The summary field however, contains the total sum of all the person's friends who have logged into the app, including those who have not granted the user_friends permission.

An example query is shown below:

GET /647733625268125?fields=context HTTP/1.1
Host: graph.facebook.com

Example response:

{
  "context": {
    "friends_using_app": {
      "data": [
        {
          "id": "7696", 
          "name": "Steve Davis"
        }, 
        {
          "id": "9074", 
          "name": "Mike Vernal"
        }, 
        {
          "id": "19094", 
          "name": "Nick Grudin"
        },
        {
          "id": "213358", 
          "name": "Bear Douglas"
        },
        {
          "id": "403902", 
          "name": "James Yu"
        }
      ], 
      "paging": {
        "next": "https://graph.facebook.com/v2.4/MAaJufefJDbOnAQTTFhTKIqeXkMm1mtgerew32x4CR/friends_using_app?limit=5&after=MTkwOTQ=", 
        "cursors": {
          "before": "NTk0Mw==", 
          "after": "MTkwOTQ="
        }
      }, 
      "summary": {
        "total_count": 259
      }
    }
  }, 
  "id": "647733625268125"
}

Context on Users

To surface social context between two people, request the context field on a User object.

The mutual_friends context edge returns a list of friends who have logged into the app, that the calling user and the subject user both have in common. As before, the summary field includes information about the total number of friends the two people have in common, including those who don't use the app being used to make the query.

Unlike the other context edges, which will return a list of users, the mutual_likes context edge returns a list of Pages which both the calling and subject user have liked in common.

An example query is shown below:

GET /3003345?fields=context HTTP/1.1
Host: graph.facebook.com

Example response:

{
  "context": {
    "mutual_friends": {
      "data": [
        {
          "id": "9074", 
          "name": "Mike Vernal"
        }, 
        {
          "id": "19094", 
          "name": "Nick Grudin"
        }, 
        {
          "id": "29395", 
          "name": "Dan Rose"
        }, 
        {
          "id": "113331", 
          "name": "Sean Ryan"
        }
      ], 
      "paging": {
        "next": "https://graph.facebook.com/v2.4/MAaJufefJtw4w4tw4fTKIqeXkMm1mVfrElwJA2x4CR/mutual_friends?limit=5&after=MTEzMzMx", 
        "cursors": {
          "before": "OTA3NA==", 
          "after": "MTEzMzMx"
        }
      }, 
      "summary": {
        "total_count": 93
      }
    }, 
    "mutual_likes": {
      "data": [
        {
          "category": "Media/news/publishing", 
          "name": "Facebook Live", 
          "id": "150984694912422"
        }, 
        {
          "category": "Artist", 
          "name": "Banksy", 
          "id": "1471162443107177"
        }, 
        {
          "category": "Product/service", 
          "name": "Facebook", 
          "id": "20531316728"
        }, 
        {
          "category": "Product/service", 
          "name": "Facebook Creative Labs", 
          "id": "360173827457914"
        }, 
        {
          "category": "Product/service", 
          "name": "Rdio", 
          "id": "684761261563448"
        }
      ], 
      "paging": {
        "next": "https://graph.facebook.com/v2.4/MAaJufefJDbOnAQTTFhTKIqeXkMm1mVfrElwJA2x4CR/mutual_likes?limit=5&after=Njg0NzYxMjYxNTYzNDQ4", 
        "cursors": {
          "before": "MTUwOTg0Njk0OTEyNDIy", 
          "after": "Njg0NzYxMjYxNTYzNDQ4"
        }
      }, 
      "summary": {
        "total_count": 45
      }
    }
  }, 
  "id": "3003345"
}

FAQs

Isn't this similar to the Facepile plugin?

Yes. The Social Context API is conceptually similar to the Facepile plugin in that it returns information about a person's friends' interactions with an object. The Facepile plugin works really well on the web, but it cannot be easily integrated within native mobile apps. Because the Social Context API is an API, the context field can be called from within mobile apps, with the data it returns used freely to construct a natively built facepile. This is also the reason why the context field only returns individually-identifiable information about people who have already logged into your app, maintaining and protecting the privacy of non-app users.

When I call the context edge, I only see a few users returned, but the total_count is large, is this expected?

Yes. The context field only returns the IDs and names of a person's friends who have also logged into your app. If your app is new and you have few logged in users, the context edge may not return many results with an ID and name. As more users log into your app, the number of people identifiably returned in each context edge will increase.

I'm calling the context edge on a object which I know many of my app-using friends have liked, but only five are returned, whats up?

The context field, be default only returns 5 results for each context edge. You can increase this by declaring a higher limit:

/ironman?fields=context.fields(friends_who_like.limit(200),video_watch_friends.limit(200))

I'm calling the context edge on an object I know my friend has liked, and I know my friend is using my app, but they're still not being returned by in the API, why not?

The context field respects the permissions that each person granted to the app when they logged in. With the new Facebook Login, people can independently select which permissions to grant to a given app, and so can restrict the behavior of APIs, including the context edge.

For example, if you are calling the friends_who_like context edge on a Page object, for a person to be identifiably returned in the response, they must not only have logged into your app, but also have granted both the user_friends and user_likes permissions.