Content Collection

DRAFT DOCUMENT

This is a draft API document describing an in-development API to enable Digital Signage integrations on Workplace.

This API is not available for general use at present. Content in this document, and functionality of the underlying API, are subject to change before general release.

Read-only access to curated collections that have been published on Workplace for use in Digital Signage integrations.

Overview

Concepts

A Collection on Workplace represents a curated list of content hosted on Workplace, as chosen by a person within a company, with the intent of showing that content outside of Workplace. For example, popular posts in a company-social group might be added to a collection, with the intent of showing those posts on digital signage displays within a company office location.

Collections contain Posts made in Workplace Groups, and the posts may include attachments, comments, reactions and likes, all of which may be used to render that content outside of Workplace.

Collections are created, curated and published by users on Workplace. Only published collections will be exposed via the Collections API.

Prerequisites

The Collection API is available to both Custom Integrations and Third Party Apps.

To use the API as a third party developer, you must have an app that uses the third party install model for Workplace, and that app will need to meet the Security Review and App Review compliance criteria necessary for using the relevant permissions.

Permissions

The Collections API requires the Read Collections permission (scope: read_collections).

This permission is considered to be High Sensitivity, and hence a third party app using this permission will be required to complete a yearly security review in order to retain access to the permission.

An app using the Read Collections permission may also use other permissions to achieve specific functionality within an integration, but additional permissions are not required when reading content within a published collection.

The Collection Object

Fields

Field Name	Description	Data Type
`id`	The Collection ID	`string`
`name`	The user-specified name of the Collection	`string`
`description`	The user-specified description of the Collection	`string`
`creator`	The user who created the Collection	`User`
`created_time`	The time when the Collection was created	`datetime`
`updated_time`	The time when the Collection was last updated	`datetime`
`icon`	An image resource representing the collection in icon form	`url`

Edges

Edge Name Description

Edge Name	Description
`/posts`	An array of Post objects that have been added to this Collection. Each Post object will have its own `id` and related fields & edges which can be fetched to obtain content for rendering on a digital signage display.

/posts

An array of Post objects that have been added to this Collection.

Each Post object will have its own id and related fields & edges which can be fetched to obtain content for rendering on a digital signage display.

Reading

Fetching all Collections

To fetch all Collections for a Workplace community, use the /collections edge on the community node.

This edge will return an array of all the Collections which are visible to the app making the API call, ordered by most recent update time.

Example Request

GET /community/collections HTTP/1.1
  Host: graph.facebook.com

Example Response

{
    "data": [
        {
            "id": "421097463037334"
            "name": "Example Collection 1",
            ...
        },
        {
            "id": "557687121959068"
            "name": "Example Collection 2",
            ...
        },
        ...
    ],
    ...
}

Fetching information about a Collection

To fetch information about a specific collection, you can use the ID of that collection as a Graph API node.

Example Request

GET /421097463037334 HTTP/1.1
  Host: graph.facebook.com

Example Response

{
    "id": "421097463037334"
    "name": "Example Collection 1",
    "description": "A collection of my favourite posts on Workplace",
    "creator": {
      "name": "Connor Treacy",
      "id": "100073793827353"
    }
    "created_time": "2022-09-13T10:22:48+0000"
    "updated_time": "2022-09-13T10:25:04+0000"
    "icon": "https://static.xx.fbcdn.net/rsrc.php/v3/yi/r/Z8WrdlDvF7L.png"
}

Fetching the Posts in a Collection

To fetch a list of posts in a Collection, you can use the /posts edge of the Collection node.

Example Request

GET /421097463037334/posts HTTP/1.1
  Host: graph.facebook.com

Example Response

{
    "data": [
        {
            "updated_time": "2022-09-13T10:22:48+0000",
            "message": "# Example post",
            "id": "3761754270594621_4754841131285925"
        },
        {
            "updated_time": "2022-08-05T08:44:37+0000",
            "message": "# A video walkthrough of the Collections API",
            "story": "Connor Treacy uploaded a file in the group: Collections API Team.",
            "id": "3761754270594621_4649426501827389"
        },
        ...
    ],
    ...
}

Using field expansion to simplify fetches

To reduce the number of API calls you use for showing content in a collection, you can use field expansion to fetch enough information in a single API call.

Example Request

GET /421097463037334/posts?fields=id,message,from,target,created_time,type,comments.limit(5).summary(true) HTTP/1.1
  Host: graph.facebook.com

Example Response

{
    "data": [
        {
            "id": "3761754270594621_4638999639536742",
            "from": {
                "name": "Connor Treacy",
                "id": "100073793827353"
            },
            "message": "Example post",
            "target": {
                "id": "3761754270594621",
                "name": "Example group"
            },
            "type": "status",
            "comments": {
                "data": [
                    {
                        "created_time": "2022-08-01T14:36:29+0000",
                        "from": {
                            "name": "Connor Treacy",
                            "id": "100073793827353"
                        },
                        "message": "Example comment 1",
                        "id": "4639000829536623"
                    },
                    ...
                ],
                "summary": {
                    "order": "chronological",
                    "total_count": 92,
                    "can_comment": true
                }
                ...
            },
            "reactions": ...
        },
        ...
    ],
    ...
}

Publishing

Publishing of Collections is not supported via API.

Editing

Editing of Collections is not supported via API.

Deleting

Deletion of Collections is not supported via API.

Webhooks

Fetching Collection information via API will give you accurate information about the Collection at the time the API was called. However, it's possible that the Collection was changed since the API was last invoked, and sometimes these changes require rapid action by your app.

For example, if a user accidentally included content in a Collection that was not meant for public display, their expectation would be that removing that content would also remove it from any display screens showing that content, in a timely fashion.

To ensure your app gets notified immediately of changes to the contents of a Collection, you should subscribe to the Collections webhook topic.

The Collections webhook topic will deliver webhook payloads to all subscribing apps, when the following actions occur on Workplace:

A new Collection is created
A Collection is deleted
A Post is added to a Collection
A Post is removed from a Collection
A Collection's name, description or icon is updated

The Collections webhook topic can be subscribed via the app dashboard on http://developers.facebook.com, or programmatically via the Webhook Subscription API.

Webhook Fields

The list of fields available on the collections webhook topic is still being defined.

Example Webhook Payload

The payload format for the collections webhook topic is still being defined.