Graph API Reference

Overview

The Graph API for Workplace is a programmatic way to get data in and out of Workplace. It's a low-level HTTP-based API that you can use to query data about objects in a Workplace graph.

The Graph API is named after the idea of a graph data model, where objects are represented by nodes and joined along edges. At an API level, this is how apps access the information on Workplace. The Graph API for Workplace allows for a subset of functionality of the Graph API. This functionality is limited to interactions with a Workplace community and may differ in some cases for better performance or usability.

More information about how to use the Graph API for Workplace can be found below:

Workplace Graph API Objects

The following nodes are accessible through the Workplace Graph API. A custom integration access token should be used to access all nodes.

Community

A Workplace community. The root group for your Workplace Graph API calls.

Groups

A Workplace group.

Posts

A post made in a group or on a member's profile.

Members

An account for a specific Workplace user.

To see examples of combining Graph API calls to solve specific issues, take a look at the list of Sample Apps.

Using the Graph API

Graph API Objects

The Graph API is a representation of the information on Workplace, composed of:

• Nodes - objects such as a User, a Photo, a Post, a Comment
• Edges - the connections between those "things", such as a Post's file, or a Photo's Comments
• Fields - metadata about objects, such as a person's name, or the privacy of a Group

Every item in the Workplace graph is represented by a unique id. Groups, Members, Posts and even Comments have their own ids, and these can be used to retrieve information about them from the Graph API.

Managing Your Community

Each Workplace community is kept separate from other communities, so you can only use the Graph API to access content inside your own community, and in multi-company groups where members of your community have been added.

For the purposes of Graph API access, your Community is treated as a Group. You can think of your community as a root group, under which all of your groups are added as children. To retrieve information about your community on the Graph API, you'll need your Community ID, which is retrieved programmatically from the Graph API, by making a HTTP GET request to graph.facebook.com/community with a valid app access token.

Graph API Versioning

The Graph API for Workplace is built on top of the Graph API. This means it inherits the same API versioning behavior.

Graph API versions are released approximately every three months, and changes across all Workplace and Graph APIs are published in the Graph API Changelog.

When making an API call to the Graph API, you can specify a version in the API path, as follows:

      https://graph.facebook.com/v2.11/community/groups
    

However, there are some restrictions on available versions:

• When a new version is released, it becomes the current API version, and is guaranteed to work for two years after its release.
• When an app is created, it defaults to the current API version at the time of creation, and this becomes the minimum API version available to that app.
• Apps are free to specify any API version when making API calls, but will not be able to make calls to deprecated API version, or to versions below the app's minimum API version.
• Unversioned API calls will default to the minimum API version for that app./

When a new custom integration is created, its minimum available API version will be the current API version at the time of creation. This minimum version affects both Graph API calls and Webhook subscriptions.

Checking Graph API Version

If you're unsure of which version you're using, there are some ways to check. To check which version of the Graph API can be used with your app, you can add the debug parameter to your API call.

      https://graph.facebook.com/community?debug=all
    

This will return extra debug information confirming the version being used.

      {
         "name": "Example Community",
         "privacy": "CLOSED",
         "id": "855210357923606",
         "__debug__": {
            "messages": [
               {
                  "link": "https://developers.facebook.com/docs/apps/versions/",
                  "message": "No API version was specified. This request defaulted to version v2.8.",
                  "type": "warning"
               }
            ]
         }
      }
    

If you try to use a version that is below the minimum API version for your app, the debug message will tell you.

      https://graph.facebook.com/v2.6/community?debug=all
      
      {
         "name": "Example Community",
         "privacy": "CLOSED",
         "id": "855210357923606",
         "__debug__": {
            "messages": [
               {
                  "link": "https://developers.facebook.com/docs/apps/versions/",
                  "message": "The app tried to call version v2.6. This app can only call versions v2.8 and higher, so the request defaulted to version v2.8.",
                  "type": "warning"
               }
            ]
         }
      }
    

Checking Webhook Versions

Webhook subscriptions use the minimum API version if the subscription was made via the Custom Integration popup dialog, or the specified API version is the subscription was made via the subscriptions Graph API endpoint, /app/subscriptions.

You can use the subscriptions endpoint to confirm the applied webhook version for each webhook field and topic. This endpoint requires an app access token.

      https://graph.facebook.com/v2.11/app/subscriptions
      
      {
        "data": [
          {
            "object": "group",
            "callback_url": "https://www.example.com/callback",
            "active": true,
            "fields": [
              {
                "name": "comments",
                "version": "v2.8"
              },
      ...
    

Using Access Tokens

Get an App Access Token

To make any Graph API calls for your community, you'll need to create an app and retrieve an access token. This involves creating a new app, then granting it the necessary permissions for the functionality you want to build.

To learn more about creating apps and the permission model, see the Permissions guide.