Workplace

Reported Content API

Concepts

This guide assumes familiarity with the general usage patterns of the Workplace Graph API. The Reported Content API adds new graph objects to allow actioning of content reports which are presented in the Reported Content Workplace Admin Panel page.

These objects include:

  • Content Report: Contains the information about the reporters and the reported violations of a particular content
  • Reported Content: Contains some information about the type of the reported object and its content

Conventions

Below are a set of working assumptions regarding the conventions for encoding and validity of different parts of the API. These conventions are not duplicated throughout this document as are currently in review and subject to change:

  1. Timestamps values (date time timestamp) are handled as UTC offset epoch milliseconds. The exact sub-second millisecond values may be quantised when returned.
  2. Wherever possible the API will return error messages indicating errors, so on non-2XX responses please consult the API error messages for developer feedback. These are intended for the developer and should not be surfaced to regular users.

Permissions

The permission required to make calls to the Reported Content API is read_and_action_reported_content, though you may require other permissions in order to access the content being reported.

Due to the sensitivity of the content available via this API, it is only available to developers within your organization, via Custom Integrations.

Core Flows

Once an instance administrator has enabled an integration with a case management tool (and that integration holds a valid access token) the case management tool can use its access token to sync Workplace content reports data to external cases and also propagate actions taken by moderators back to Workplace.

Reading Content Reports

Fetch the Content Reports of a company

GET /community/reported_content

This will return all unactioned reports within the company.

Read a single Content Report

GET /{content-report-id}

Content Report object fields

FieldDescriptionType
id

The content report's unique ID

string

content_author

A single

community member

object representing the Workplace user that authored the content.

User

reported_content

The content object that has been reported

Reported Content

reporters

A list of users who reported the content, along with their reason for doing so.

Array of objects containing the following fields:

  • id - The ID of the user who reported the content
  • name - The name of the user who reported the content
  • violation_category - the category of violation as specified by the user who reported the content
  • explanation - A message provided by the user when reporting the content
  • timestamp - A UTC timestamp of the time of the report

Read reported content

GET /{content-report-id}/reported_content

Reported Content object fields

FieldDescriptionType
id

The reported content's unique ID.

string

comment_count

Number of comments on the reported content, if applicable.

int32

creation_time

Content creation time.

Timestamp UTC

description

Description of the reported object, if applicable. E.g. the description of a reported event.

string

group

A

Group

object representing the group where the content has been posted, if applicable.

Group
likes_count

Number of likes on the reported content, if applicable.

int32

name

Name of the reported object, if applicable. E.g. the name of a reported event.

string

preview

“Preview” text snippet of the reported content, if applicable. E.g. the text of a reported post.

string

uri

A link to the reported content.

url

Actioning Content Reports

Allow the reported content to stay on Workplace

POST /{report-id}/allow_content

This action removes the report and doesn’t affect the content.

Delete the reported content

POST /{report-id}/delete_content

This action removes both the report and the content.

Hide the reported content

POST /{report-id}/quarantine_content

This action hides the reported content and does not remove the report. A typical use-case is when a content needs to be hidden while the decision is made whether it’s violating or not. The content can later be restored via the restore action.

Restore the reported content

POST /{report-id}/unquarantine_content

This action restores content that has been hidden via the hide action (A3) and does not remove the report.

Reading Content Reports Statistics

Read the number of actioned reports

GET /community/reported_content?
  summary=allowed_content_count.days(30),
          deleted_content_count.days(30)

Both allowed_content_count and deleted_content_count are parameterized fields and you should pass the aggregation window size in days.

Webhooks

The Reported Content API also supports webhooks for related topics and fields, following the Workplace webhook conventions.

These webhooks follow the same conventions in terms of data shapes as the above. Please refer to the Workplace Webhook reference for details relating to payload format. Webhooks allow subscription to changes in a field set on a specific topic.

Note that webhook fields do not represent entity fields.

  • Topic: Content Report
    • Field: reported_content - called when a Workplace user reports a content.

Example webhook body for content report

Below is an illustration of the body for a content report web hook notification.

{
  "object":"reported_content",
  "entry":[
    {
      "id":"{report_id}",
    }
    , ...
  ]
}

A single Webhook call may include a batch of new reports in the entry array.

Related Permissions

While this document is predominantly related to reported content related features which use the read_and_action_reported_content permission granted during app review, there are a number of other feature permissions that are likely to be needed to create fully-featured integrations.